@eltonssouza/development-utility-kit 0.10.1 → 0.12.0

package/.claude/skills/README.md

@@ -1,6 +1,6 @@
 # Skills — Cowork + Claude Code
 
-> **Breaking change (2026-05-25)**: command layer deleted. Architecture is now 100% Skills + Agents. The `project-manager` skill is the **front-controller** entry point (ADR-041): it intercepts every prompt, enforces the flow order, and routes/orchestrates to the appropriate specialist agent(s). Specific skills (run-sprint, auto-test-guard, prd-ready-check, grill-me, scaffold, pair-debug, api-integration-test, brain-keeper, test-coverage-auditor, update-template, active-project, caveman) still take priority via keyword match. Standard sprint flow: `analyst` (plan) → `tech-lead` (ADR + approve) → `sprint-runner` (executes Sprint N delegating to `backend-developer` + `frontend-developer` + `database-engineer` in parallel) → `gate-keeper` (gate senior+) → `code-reviewer` → `tech-lead` (merge).
+> **Breaking change (2026-05-25)**: command layer deleted. Architecture is now 100% Skills + Agents. The `project-manager` skill is the **front-controller** entry point (ADR-041): it intercepts every prompt, enforces the flow order, and routes/orchestrates to the appropriate specialist agent(s). Specific skills (run-sprint, auto-test-guard, prd-ready-check, grill-me, scaffold, pair-debug, api-integration-test, brain-keeper, test-coverage-auditor, update-template, caveman) still take priority via keyword match. Standard sprint flow: `analyst` (plan) → `tech-lead` (ADR + approve) → `sprint-runner` (executes Sprint N delegating to `backend-developer` + `frontend-developer` + `database-engineer` in parallel) → `gate-keeper` (gate senior+) → `code-reviewer` → `tech-lead` (merge).
 
 This directory contains the **Skills** that Cowork and Claude Code use to develop fullstack software Java 25+ / Spring Boot 4.0+ / Angular 21+ with this template's standard flow.
 
@@ -23,8 +23,7 @@ When the user describes a task, Cowork must **deliver it 100% production-ready f
 | [`pair-debug`](pair-debug/SKILL.md) | Hypothesis-driven debug loop: state symptom → formulate hypotheses → probe one at a time → confirm cause → fix minimal → write test. Bans "try and see" approach. | "pair debug", "investigate this bug", "find the root cause", "why is this not working" |
 | [`grill-me`](grill-me/SKILL.md) | Discovery interview — one question at a time, with recommendation, until requirements are clear. Persists conclusions to `docs/plans/PLAN_*.md` or ADR. | "grill me", "interview me about", "stress-test the plan", "discover requirements with me" |
 | [`brain-keeper`](brain-keeper/SKILL.md) | Upon completing a PLAN_*: records history in the Obsidian vault (`docs/brain/`) — daily, feature, ADR, bug, tech-debt + updates MOC. Provisions `.obsidian/` with per-folder color snippet on first run. | End of PLAN_*; "record in the brain", "update brain", "log of the day", "close feature in vault" |
-| [`update-template`](update-template/SKILL.md) | Adopts or synchronizes an EXISTING project with the latest version of the template (merge with backup) | "update the template", "bring the new skills", "sync with development-utility-kit", "adopt the template here" |
-| [`active-project`](active-project/SKILL.md) | Path-driven, non-interactive adoption of a project to the template — `/active-project <path>`. Fast lane of `update-template` (no preview/checkpoint). Preferred for scripted batch adoptions. | "/active-project `<path>`", "ativar projeto em `<path>`", "adota o projeto `<path>`", "aplica o template em `<path>`" |
+| [`update-template`](update-template/SKILL.md) | Adopts or synchronizes an EXISTING project with the latest version of the template (merge with backup). For scripted/batch adoption use `duk install` (single project) or `duk sync-all <dir>` (many projects) from the terminal. | "update the template", "bring the new skills", "sync with development-utility-kit", "adopt the template here" |
 | [`caveman`](caveman/SKILL.md) | Telegraphic output style — drops articles, filler, pleasantries. 65-75% fewer tokens. Always active; adjustable via "caveman lite\|full\|ultra" or "stop caveman". | Passive (always active); "caveman lite", "caveman ultra", "stop caveman" |
 | [`to-prd`](to-prd/SKILL.md) | Transforms a `DISCOVERY_*.md` into a Product Requirements Document. Requires `grill-me` to have run first. Produces `docs/prd/PRD_*.md` with six required sections: Overview, Goals, User Stories (prose), Functional Requirements, Non-functional Requirements, Out of scope. Idempotent. Opt-in only — never auto-triggered. | "to-prd", "gera PRD", "cria PRD", "generate PRD", "create PRD" |
 | [`to-issues`](to-issues/SKILL.md) | Decomposes a `PRD_*.md` into trackable GitHub issues. Requires `to-prd` to have run first. Produces `docs/issues/ISSUES_*.md` with `[ISSUE-N]` blocks (Labels, Body, Acceptance criteria) ready for `gh issue create`. Idempotent. Opt-in only — never auto-triggered. | "to-issues", "quebra em issues", "gera issues", "break into issues", "generate issues" |
@@ -163,7 +162,7 @@ USER MESSAGE
   │     │   to-prd, to-issues → analyst / product-owner
   │     │
   │     └─ Pattern 3 (Standalone)    → no agent; executes inline
-  │         caveman, pair-debug, project-manager, active-project,
+  │         caveman, pair-debug, project-manager,
   │         prd-ready-check, api-integration-test, test-coverage-auditor
   │
   └─ no specific skill → PROJECT-MANAGER SKILL (front-controller, ADR-041)
@@ -178,7 +177,7 @@ For names that exist in both skill + agent (`sprint-runner`, `gate-keeper`, `bra
 
 ### When a name exists only in one layer
 
-- **Skill only** (`caveman`, `pair-debug`, `grill-me`, `active-project`, `project-manager`, `to-prd`, `to-issues`, `prd-ready-check`, `api-integration-test`, `test-coverage-auditor`): execute inline or orchestrate via Bash/Read/Write/Task. No dedicated agent counterpart. See Pattern 3 in `## Pattern catalog` below. The last three were demoted to Pattern 3 in ADR-037 (their same-name agents never existed on disk; the calling session executes them inline).
+- **Skill only** (`caveman`, `pair-debug`, `grill-me`, `project-manager`, `to-prd`, `to-issues`, `prd-ready-check`, `api-integration-test`, `test-coverage-auditor`): execute inline or orchestrate via Bash/Read/Write/Task. No dedicated agent counterpart. See Pattern 3 in `## Pattern catalog` below. The last three were demoted to Pattern 3 in ADR-037 (their same-name agents never existed on disk; the calling session executes them inline).
 - **Agent only** (`tech-lead`, `product-owner`, `architect`, `security-engineer`, `database-engineer`, `devops-engineer`, `code-reviewer`, `ux-designer`, `analyst`, `backend-developer`, `frontend-developer`, `qa-engineer`, `mobile-developer`, `n8n-specialist`, `migrator`, `release-engineer`, `auditor`): invoked via Task tool by skills — commonly by `project-manager` (for tasks without a dedicated skill) or by `sprint-runner` (for sprint tasks).
 
 ### Required mapping in router skills
@@ -257,7 +256,7 @@ A skill with **no companion agent**. It executes its logic inline (Bash, Read, W
 |---|---|---|
 | **Mode/style** | Changes the output style of the parent session, not a task | `caveman` |
 | **Router/front-controller** | Intercepts every prompt, enforces flow order, dispatches (no fixed agent target) | `project-manager` |
-| **Inline transform** | Short-lived transformation that doesn't warrant a dedicated agent | `active-project` |
+| **Inline transform** | Short-lived transformation that doesn't warrant a dedicated agent | `pair-debug` |
 | **Interview / generation** | Multi-turn interview + file write, no persistent agent needed | `pair-debug`, `to-prd`, `to-issues`, `grill-me`* |
 
 *`grill-me` is listed here for its inline interview phase; its output handoff to `analyst` makes it also Pattern 2. Primary classification: Pattern 2.
@@ -269,7 +268,6 @@ A skill with **no companion agent**. It executes its logic inline (Bash, Read, W
 | `caveman` | Mode — output style toggle |
 | `pair-debug` | Inline transform — hypothesis loop, no persistent executor |
 | `project-manager` | Router/front-controller (ADR-041) — intercepts every prompt; fixed agent target undefined by design |
-| `active-project` | Inline transform — fast-lane adoption, no dedicated agent |
 | `prd-ready-check` | Inline gate — production checklist executed in the calling session (per ADR-037); needs Chrome MCP + Bash inline, would lose tools if dispatched to a child |
 | `api-integration-test` | Inline probes — docker compose + curl + Chrome MCP run in the calling session (per ADR-037); dispatch to a child would lose Chrome MCP access |
 | `test-coverage-auditor` | Inline scan — Glob/Grep over source + dailies, writes to tech-debt.md directly (per ADR-037); stateless instruction set |

package/.claude/skills/project-manager/SKILL.md

@@ -59,7 +59,6 @@ Specific skills always win — never compete:
 | "record in the brain", "update vault" | `brain-keeper` |
 | "audit coverage", "test debt" | `test-coverage-auditor` |
 | "update template", "sync development-utility-kit" | `update-template` |
-| "/active-project <path>" | `active-project` |
 | "caveman lite/full/ultra", "stop caveman" | `caveman` |
 
 Also do NOT trigger for trivial single-file edits — just do them inline in the calling session.

package/.claude/skills/scaffold/SKILL.md

@@ -36,7 +36,7 @@ If `Project type` is missing or unrecognized, the `scaffold` agent routes to `te
 - Implementing features after scaffold is complete — use `backend-developer` / `frontend-developer`.
 - Migrating an existing project to a newer stack — use `migrator`.
 - Updating the harness template — use `update-template`.
-- Adopting the template in an existing project — use `active-project`.
+- Adopting the template in an existing project — use `update-template` (or `duk install` from the terminal).
 
 ## Dispatch
 

package/.claude/skills/update-template/SKILL.md

@@ -231,8 +231,8 @@ Previously the harness shipped a separate `auditor` agent (`.claude/agents/audit
 
 ### Triggering audit-only mode
 
-- "/active-project `<path>` --dry-run" — non-interactive audit from outside the project.
 - "audit the .claude structure here" — interactive audit from inside the project. The skill detects the audit intent in the prompt and skips Step 5 (Execute) — only Steps 1-4 (preview report) run.
+- `duk install --check-only` — non-interactive audit from the terminal (detects stack + reports drift without writing).
 - PT: "audita a estrutura claude", "compara com o template", "verifica desatualizado".
 
 ### What audit mode reports
@@ -242,7 +242,7 @@ For each diff vs the template:
 - Divergent files (content drift).
 - Outdated agents/skills (older version than template).
 - Risk classification per finding: high (missing critical agent), medium (drift in non-critical file), low (cosmetic).
-- Recommendation: which command to run to fix (`duk install` from inside, `/active-project <path>` from outside).
+- Recommendation: which command to run to fix (`duk install` from inside the project, or `duk install --check-only` to preview first).
 
 ### Safety rule (inherited from auditor agent)
 

package/CLAUDE.md

@@ -105,7 +105,6 @@ Skills in `.claude/skills/` trigger automatically by keyword. **Single entry lay
 | `update-template` | "update template", "sync with development-utility-kit" | Syncs `.claude/`, `CLAUDE.md` (merge + backup, hash-based drift detection) — preserves `Project Identity` |
 | `to-prd` | "to-prd", "gera PRD", "cria PRD" (opt-in, after `grill-me`) | Reads `DISCOVERY_*.md` → writes `docs/prd/PRD_*.md` |
 | `to-issues` | "to-issues", "quebra em issues", "gera issues" (opt-in, after `to-prd`) | Reads `PRD_*.md` → writes `docs/issues/ISSUES_*.md` ready for `gh issue create` |
-| `active-project` | "ativar projeto em `<path>`", "adota o projeto `<path>`" | Path-driven, non-interactive adoption — fast lane of `update-template` |
 
 See [`.claude/skills/README.md`](.claude/skills/README.md) and [`.claude/stacks/README.md`](.claude/stacks/README.md).
 

package/README.md

@@ -1,416 +1,53 @@
 # development-utility-kit
 
-> Meta-skill harness for Claude Code. Generic agents by domain, knowledge packs by stack, single-`npx` injection into any project.
+> Meta-skill harness for Claude Code. Stack-agnostic agents, knowledge packs per stack, single-command injection into any project.
 
 [![npm](https://img.shields.io/npm/v/@eltonssouza/development-utility-kit)](https://www.npmjs.com/package/@eltonssouza/development-utility-kit)
-[![beta](https://img.shields.io/npm/v/@eltonssouza/development-utility-kit/beta?label=beta)](https://www.npmjs.com/package/@eltonssouza/development-utility-kit?activeTab=versions)
-[![downloads](https://img.shields.io/npm/dt/@eltonssouza/development-utility-kit)](https://www.npmjs.com/package/@eltonssouza/development-utility-kit)
-[![license](https://img.shields.io/npm/l/@eltonssouza/development-utility-kit)](LICENSE)
-[![stars](https://img.shields.io/github/stars/eltonssouza/development-utility-kit?style=social)](https://github.com/eltonssouza/development-utility-kit/stargazers)
-[![issues](https://img.shields.io/github/issues/eltonssouza/development-utility-kit)](https://github.com/eltonssouza/development-utility-kit/issues)
-[![roadmap](https://img.shields.io/badge/roadmap-public-blue)](ROADMAP.md)
-[![comparisons](https://img.shields.io/badge/comparisons-honest-orange)](docs/COMPARISONS.md)
-[![release](https://img.shields.io/github/v/release/eltonssouza/development-utility-kit)](https://github.com/eltonssouza/development-utility-kit/releases/latest)
+[![license](https://img.shields.io/npm/l/@eltonssouza/development-utility-kit)](https://github.com/eltonssouza/development-utility-kit/blob/main/LICENSE)
 
 CLI binary: `duk` · Node `>=18` · License: MIT
 
-```bash
-npx @eltonssouza/development-utility-kit install
-```
-
----
-
-## What it is
-
-Not an agent. Not a skill. The **bundle** that turns any repo into a Claude-Code-driven project — with:
-
-- **20 keyword-triggered skills** (front-controller `project-manager`, `run-sprint`, `auto-test-guard`, `pair-debug`, `grill-me`, `to-prd`, `to-issues`, `quick-feature`, `brain-keeper`, `stack-discovery`, `create-stack-pack`, `quality-standards`, `caveman`, etc.)
-- **21 specialized sub-agents** (1 Opus for `tech-lead`, 3 Haiku for mechanical work, 17 Sonnet for everything else)
-- **5 stack knowledge packs** (Java + Spring Boot 3/4, Angular 18/19/21) — extend with `create-stack-pack` skill
-- **Full discovery → delivery pipeline** (`grill-me → to-prd → to-issues → analyst → run-sprint`) with mandatory TDD
-- **Local sub-agent telemetry** (`SubagentStop` hook → SQLite) + **web dashboard** (Express + Vanilla JS + Chart.js CDN)
-- **Non-negotiable Senior+ quality gate** (coverage ≥85%, mutation ≥70%, Lighthouse ≥0.80, a11y 0 critical)
-- **Autonomy Matrix**: agents decide on their own; human is interrupted only in 4 PO cases or 3 TL cases
-- **Drift detection** via `.claude/.MANIFEST` (sha256 per file) — `duk install` refuses to overwrite local modifications without `--force`
-
-> v2.0.0+ introduces **stack-agnostic agents** consuming knowledge packs at `.claude/stacks/<lang>/<framework>-<major>.md`. The pre-1.0 era of hardcoded Java/Angular agents is gone — agents now adapt to the declared stack via `STACK CONTEXT` injection (ADR-026).
-
----
-
-## Why use it
-
-| Strength | Detail |
-|---|---|
-| **Zero-friction injection** | `duk install` in the project directory. No clone, no git, no boilerplate. |
-| **Stack-agnostic agents** | `backend-developer`, `frontend-developer`, `mobile-developer`, etc. read `## Project Identity` and consume the matching stack pack. Works on Java, TypeScript, Python, Go, etc. |
-| **Knowledge packs by version** | Java SB3 vs SB4 vs SB5 each get their own `## Code patterns`, `## Security`, `## Anti-patterns` section. No pack? `create-stack-pack` skill generates one conversationally. |
-| **Auto stack detection** | `detect-stack.js` parses `pom.xml`, `package.json`, `pyproject.toml`, `go.mod`, `docker-compose.yml`. |
-| **Idempotent install + drift detection** | Previous `.claude/` becomes `.claude.bak-<timestamp>/`. `.MANIFEST` (sha256) detects local modifications and refuses unsafe overwrites. `## Project Identity` preserved verbatim. |
-| **Local overrides via `.claude/local/`** | Project-specific tweaks live there. Never touched by `duk install`. Loader priority: `local/` wins over harness. |
-| **Aggressive autonomy by design** | Agents never ask permission for routine. PO/TL hold decision power; specialists never escalate directly to human. |
-| **Universal TDD** | `sprint-runner` enforces `qa-engineer (failing test) → developer → gate-keeper` on every task. ADR-020. |
-| **Obsidian-ready brain** | `brain-keeper` provisions `docs/brain/` with vault, color snippets, MOC, ADRs, daily, features, bugs, tech-debt, migrations. |
-| **Caveman mode by default** | ~65–75% cheaper output in tokens, no technical loss. ULTRA in code, FULL in `.md`. Credit: [@JuliusBrussee](https://github.com/JuliusBrussee). |
-| **No build for dashboard** | Vanilla JS + Chart.js via CDN. Tiny tarball. ADR-014. |
-
----
-
-## How it works
-
-### 3-layer architecture
-
-```
-User prompt
-    │
-    ▼
-┌─────────────────────────────┐
-│  SKILLS (entry point)       │  keyword match
-│  .claude/skills/<X>/SKILL.md│  → specific skill OR
-└─────────────┬───────────────┘    project-manager (front-controller)
-              │
-              ▼  Step 0 (orchestrating skills)
-┌─────────────────────────────┐
-│  stack-resolver (Haiku)     │  reads ## Project Identity
-│  reads .claude/stacks/<pack>│  returns STACK CONTEXT block
-└─────────────┬───────────────┘
-              │
-              ▼  Task tool dispatch (with STACK CONTEXT inlined)
-┌─────────────────────────────┐
-│  AGENTS (executors)         │  21 specialized agents
-│  .claude/agents/<X>.md      │  Opus | Sonnet | Haiku per matrix
-└─────────────┬───────────────┘
-              │
-              ▼
-   Artifact (code, ADR, PRD, plan, test, deploy)
-```
-
-Skill = entry point + multi-step protocol. Agent = executor with tools. Pack = stack-specific knowledge consumed by agents. No loose commands.
-
-### Discovery → delivery flow
-
-```
-grill-me          → docs/discovery/DISCOVERY_<NAME>.md
-   ↓
-to-prd            → docs/prd/PRD_<NAME>.md
-   ↓
-to-issues         → docs/issues/ISSUES_<NAME>.md   (gh issue create-ready)
-   ↓
-analyst           → docs/plans/PLAN_<NAME>.md       (goal-ready DoD)
-   ↓
-run-sprint (thin) → sprint-runner (single execution contract; mandatory TDD, Stage 0 stack-resolver)
-   ↓
-gate-keeper       → Senior+ gate (coverage, mutation, a11y, lighthouse, pyramid)
-   ↓
-brain-keeper      → docs/brain/ (daily, feature, ADR, bug, tech-debt, migration, MOC)
-```
-
-For small features that don't justify the full pipeline (adding a field, fixing a search, exporting CSV): use `quick-feature` skill — bypasses discovery/PRD/issues, generates minimal PLAN, dispatches `run-sprint` directly. TDD + Senior+ gate still mandatory.
-
-### Flow governance
-
-Every prompt passes through `flow-guard.js` (UserPromptSubmit hook) before reaching the model. It injects `[FLOW STATE]`, classifies the lane (greenfield / brownfield / sprint / small-task), and hard-blocks qualified implementation work that is missing its prerequisite artifact (DISCOVERY_*.md or PLAN_*.md). Bypass is audited in `.flow-state.json`.
+## Install
 
-`project-manager` is the universal front-controller: classifies the lane, enforces the stage order, then dispatches (ROUTE → 1 specialist | ORCHESTRATE → ≤5 parallel with a shared `run_group_id` | ESCALATE → `sprint-runner`).
-
-### Telemetry + Dashboard
+**As a Claude Code plugin** (recommended — global, every project, nothing written into your repo):
 
 ```
-Claude Code ─► UserPromptSubmit ─► flow-guard.js   (lane classify + block)
-            │
-            └► SubagentStop hook ─► subagent-telemetry.sh ─► telemetry-writer.js
-                                                                  │
-                                                                  ▼
-                                                    ~/.claude/telemetry.db (SQLite)
-                                                         events + orchestration_runs
-                                                                  │
-                        ┌─────────────────────────────────────────┘
-                        ▼
-              duk dashboard  →  Express @ :4242+  →  Vanilla JS UI
-                               /api/stats
-                               /api/projects
-                               /api/projects/processes   (run-groups + agent children)
-                               /api/rtk                  (rtk gain --format json)
+/plugin marketplace add eltonssouza/development-utility-kit
+/plugin install development-utility-kit
 ```
 
-Polling every 5s. Click a project → **Processes panel** shows recent orchestration run-groups, each expandable into its parallel agent fan (agent type, model, status). Phase A: completed runs. Phase B (live in-flight): deferred — no `SubagentStart` hook available in Claude Code today.
-
----
-
-## Quickstart
-
-### Brand-new project
+**Or inject per-project via npx** (writes `.claude/` + `CLAUDE.md` into the current project, and self-installs the `duk` CLI globally):
 
 ```bash
-duk new my-app
-cd my-app
-# Open Cowork or Claude Code in this folder, then in chat:
-# > "sabatina pra projeto novo"
-# stack-discovery skill walks you through 8 questions to declare type, language,
-# framework, version, database, UI lib, domain.
-```
-
-### Existing project
-
-```bash
-cd <your-project>
 npx @eltonssouza/development-utility-kit install
 ```
 
-Injects `.claude/`, `CLAUDE.md`, `.claude/HARNESS_VERSION`, `.claude/.MANIFEST`, `.claude/local/` placeholder. Detects stack automatically.
-
-**Preview before applying** (no writes):
-```bash
-duk install --check-only
-```
-
-Reports detected stack + local vs latest harness version + pack availability.
+> Run `npx … install` from inside a project folder — not from a drive root.
 
-**Override local modifications** (skip drift detection):
-```bash
-duk install --force
-```
-
-`.claude.backup-<timestamp>/` is always created.
-
-### Edit `## Project Identity` in `CLAUDE.md`
-
-The only section the project owns. All others are harness base and receive updates via `duk install` (with drift detection).
-
-```markdown
-## Project Identity
-
-- **Project name**: my-store
-- **Project type**: fullstack
-- **Primary stack**: Java 21 + Spring Boot 3.2
-- **Database**: PostgreSQL 17 + Redis 7
-- **Domain**: e-commerce
-- **Team size**: 3 fullstack
-```
-
-`stack-resolver` reads this and loads `.claude/stacks/java/spring-boot-3.md`. If pack absent for declared stack: dispatches `create-stack-pack` skill to author it conversationally.
-
-### Run the dashboard
-
-```bash
-duk dashboard            # auto-detects free port from 4242
-duk dashboard --port 5000
-duk dashboard --no-open  # skip browser launch
-```
+## What you get
 
-Before starting Express, prints `rtk gain` (token savings analytics). If `rtk` not in PATH: non-fatal warning, proceeds.
-
-### Update many projects at once
-
-```bash
-# Preview which projects would be updated:
-duk sync-all C:\development\source\projects
-
-# Apply with filters (AND logic between multiple --filter):
-duk sync-all C:\development\source\projects --filter stack:java --apply
-duk sync-all C:\development\source\projects --filter age:30d --apply
-duk sync-all C:\development\source\projects --filter harness-version:<2 --apply
-
-# Exclude specific projects:
-duk sync-all C:\development\source\projects --exclude prod-critical --apply
-```
-
----
+- **18 keyword-triggered skills** + **21 stack-agnostic agents** + stack knowledge packs (Java/Spring, TypeScript/Angular, and more)
+- **Front-controller routing** (`project-manager`) + flow governance hook
+- **Full discovery → delivery pipeline** with mandatory TDD and a Senior+ quality gate
+- **Local sub-agent telemetry** + a no-build web dashboard (`duk dashboard`)
+- **Obsidian project brain** (`brain-keeper`)
 
 ## `duk` commands
 
 ```
-duk new <name>                                       # scaffold new project + open conversational discovery
-duk install [--sub <dir>] [--dry-run] [--check-only] [--force]
-                                                     # inject harness into CWD (idempotent)
-duk update                                           # alias of install
-duk sync-all <dir> [--filter <expr>]* [--exclude <name>]* [--apply]
-                                                     # update harness in many projects
-duk dashboard [--port <n>] [--no-open]               # launch local dashboard
-duk doctor [--strict] [--json]                       # validate environment (Node, git, hooks, packs)
-duk lint [--category <name>] [--json]                # validate harness .claude/ structure
-duk help [command]                                   # general help or command-specific
-duk --version                                        # print version
+duk new <name>          # scaffold a new project + conversational stack discovery
+duk install             # inject the harness into the current project
+duk install --check-only # preview detected stack + drift, write nothing
+duk sync-all <dir>      # update the harness across many projects
+duk dashboard           # launch the local telemetry + docs dashboard
+duk doctor              # validate environment
+duk lint                # validate harness .claude/ structure
+duk help [command]      # help
 ```
 
-See `duk help <command>` for detailed per-command flags. The `doctor` and
-`lint` commands are deterministic and run without any LLM/API calls — safe
-to use in CI. See **ADR-034** for the design principle behind them.
-
----
-
-## Prompts that trigger skills
-
-| You say | Skill fires |
-|---|---|
-| "sabatina pra projeto novo", "stack discovery" | `stack-discovery` → fills `## Project Identity` |
-| "cria pack para Django", "gera pack" | `create-stack-pack` → new `.claude/stacks/<lang>/<framework>-<major>.md` |
-| "grill me", "interview me about X" | `grill-me` → discovery interview |
-| "to-prd", "generate PRD" | `to-prd` (after `grill-me`) |
-| "to-issues", "break into issues" | `to-issues` (after `to-prd`) |
-| "run sprint 2", "execute the sprint" | `run-sprint` (Stage 0 stack-resolver) |
-| "quick-feature: add field X" | `quick-feature` → bypass discovery, minimal PLAN, run-sprint |
-| "pair debug", "investigate this bug" | `pair-debug` (Stage 0 stack-resolver) |
-| "audit coverage" | `test-coverage-auditor` |
-| "PRD-ready?", "ready for prod?" | `prd-ready-check` |
-| "create endpoint", "build the screen", anything else | `project-manager` (front-controller — classifies lane, enforces flow) |
-| "stop caveman", "normal mode" | disables caveman |
-
----
-
-## Senior+ Quality Gate
-
-Non-negotiable. `gate-keeper` blocks merge if any item fails. **Thresholds are universal across stacks**; tooling specifics (JaCoCo vs coverage.py, JUnit vs pytest, etc.) come from the active stack pack:
-
-| Metric | Threshold |
-|---|---|
-| Backend coverage (lines / branches) | ≥85% / ≥80% |
-| Backend mutation score | ≥70% in domain + application layers |
-| Frontend coverage | ≥85% statements, ≥80% branches |
-| Static analysis (SpotBugs / mypy / golangci-lint / ESLint strict / ...) | 0 CRITICAL, 0 HIGH |
-| Dependency vuln scan (OWASP DC / npm audit / safety / govulncheck) | 0 CVE CVSS ≥7.0 |
-| Playwright E2E | 100% green, console 0 errors |
-| a11y (jest-axe + axe-playwright) | 0 serious, 0 critical |
-| Lighthouse | score ≥0.80, LCP ≤2500ms, CLS ≤0.1, TBT ≤300ms |
-| Testing pyramid | E2E ≤30% of total (ideal ≤15%) |
-
-Reference: ADR-007 (a11y + Lighthouse + pyramid), ADR-027 (pack `## Security` mandatory).
-
----
-
-## Structure
-
-```
-development-utility-kit/
-├── .claude/
-│   ├── skills/      # 20 skills (project-manager front-controller, run-sprint, stack-discovery, ...)
-│   ├── agents/      # 21 agents (Opus/Sonnet/Haiku per matrix)
-│   ├── stacks/      # 5 stack packs (java/spring-boot-3, spring-boot-4; typescript/angular-18,19,21)
-│   │   ├── _template.md
-│   │   ├── README.md
-│   │   ├── CODEOWNERS
-│   │   ├── java/
-│   │   └── typescript/
-│   └── settings.json
-├── bin/
-│   ├── cli.js       # zero-deps `duk` CLI router (Node 18+)
-│   └── lib/         # 8 helper modules (detect-stack, version-check, sync-all, manifest, ...)
-├── dashboard/
-│   ├── server.js    # Express + 3 endpoints
-│   ├── db.js        # better-sqlite3 / sql.js wrapper
-│   ├── rtk.js       # spawns rtk gain --format json
-│   └── public/      # Vanilla JS + Chart.js CDN
-├── scripts/
-│   ├── hooks/
-│   │   ├── subagent-telemetry.sh    # SubagentStop hook
-│   │   └── telemetry-writer.js      # triple-fallback writer
-│   ├── lint-harness.mjs             # validates Pattern 1/2, packs, agent hardcode, drift
-│   └── latest-versions.json         # offline fallback for version detection
-├── docs/
-│   ├── brain/       # Obsidian vault (features, decisions, daily, bugs, migrations)
-│   ├── discovery/   # DISCOVERY_*.md
-│   ├── prd/         # PRD_*.md
-│   ├── issues/      # ISSUES_*.md
-│   └── plans/       # PLAN_*.md
-├── tests/smoke/     # smoke tests (install, dashboard, telemetry)
-├── .github/workflows/
-│   ├── publish.yml             # auto-publish on GitHub Release published
-│   └── promote-dist-tag.yml    # manual: promote beta → latest via Actions UI
-├── CLAUDE.md        # base template (Project Identity + plugin base)
-├── CHANGELOG.md     # release-please-managed
-└── package.json
-```
-
----
-
-## Key ADRs
-
-| ADR | Decision |
-|---|---|
-| **ADR-007** | Senior+ gate (a11y + Lighthouse + pyramid thresholds) |
-| **ADR-008** | Standard pipeline (PO → analyst → tech-lead → sprint-runner → gate-keeper → reviewer → TL) |
-| **ADR-011** | `grill-me` as opt-in discovery skill |
-| **ADR-014** | Vanilla JS + Chart.js CDN dashboard |
-| **ADR-015** | Triple-fallback telemetry writer |
-| **ADR-017** | `DISCOVERY_*.md` in `docs/discovery/` (not `docs/plans/`) |
-| **ADR-018** | `duk` CLI redesign — `install → adoptProject` |
-| **ADR-020** | Mandatory TDD in `sprint-runner` |
-| **ADR-026** | Generic agents + stack packs (architecture foundation) |
-| **ADR-027** | Pack governance (frontmatter + `## Security` mandatory + CODEOWNERS + annual review) |
-| **ADR-028** | `duk` workflow (new, install --check-only, sync-all with filters, help) |
-| **ADR-029** | Canonical pack format (10 sections, 300-450L target) |
-| **ADR-030** | Migrator consumes 2 packs (FROM + TO), multi-major incremental, fullstack sequential |
-| **ADR-032** | Drift detection (`.MANIFEST`) + `.claude/local/` overrides + opt-in propagation |
-| **ADR-033** | `project-manager` orchestrate mode (ROUTE / ORCHESTRATE ≤5 / ESCALATE) — fast-lane for ad-hoc multi-domain tasks without a formal `PLAN_*.md` |
-| **ADR-034** | CLI vs Skill design principle — mechanical/deterministic → `duk` CLI; contextual/judgment → chat (skills + agents); hybrid → CLI executes + skill orchestrates |
-
-Full vault under [`docs/brain/`](docs/brain/) — browse via Obsidian. Live ADR index also rendered at `duk dashboard` → Tech Docs tab.
-
----
-
-## Commit restrictions (NON-NEGOTIABLE)
-
-- Conventional Commits (`feat(scope): ...`, `fix(scope): ...`, `feat!: ...` for breaking)
-- **Never** reference Anthropic, Claude, AI, LLM, or assistant in subject/body/trailers
-- **Never** add `Co-Authored-By: Claude`
-- Commits must look 100% authored by the human developer
-- `tech-lead` rejects merge on violation
-
----
-
-## Acknowledgements
-
-`development-utility-kit` is a **meta-skill harness** — it ships its own skills and agents, but it also stands on the shoulders of skills built by other people in the Claude Code community. The bundle would not work the way it does without them, and the credit belongs to their authors.
-
-Honest thanks to:
-
-- **[`grill-me`](https://github.com/mattpocock/skills)** — by **[Matt Pocock](https://github.com/mattpocock)** ([aihero.dev](https://www.aihero.dev/my-grill-me-skill-has-gone-viral)). The relentless discovery interview that opens our `grill-me → to-prd → to-issues → analyst → run-sprint` pipeline is Matt's design. We adapted the skill to persist its output to `docs/discovery/DISCOVERY_*.md` and hand off to `analyst`, but the interview mechanic — one decision branch at a time, with a recommended answer the user just confirms — is his.
-- **[`caveman`](https://github.com/JuliusBrussee/caveman)** — by **[Julius Brussee](https://github.com/JuliusBrussee)**. The telegraphic communication mode that saves us 65–75% of output tokens with zero technical loss. We use it as the default style in this harness; the compression rules, the levels (lite/full/ultra), and the auto-clarity carve-outs are Julius's work.
-- **[`impeccable`](https://github.com/pbakaus/impeccable)** — by **[Paul Bakaus](https://github.com/pbakaus)**. The design-refinement skill (`polish | harden | audit`) that drives our visual-quality gate. Paul's `npx skills add pbakaus/impeccable` distribution pattern also directly inspired our own `npx @eltonssouza/development-utility-kit install` installer (ADR-018).
-- **[`rtk`](https://github.com/rtk-ai/rtk)** — by the **[rtk-ai](https://github.com/rtk-ai) team**. The Rust Token Killer CLI proxy that powers the live "RTK savings" widget on the `duk dashboard` (`rtk gain --format json` → `/api/rtk`). The 60–90% savings on dev operations we surface in the dashboard are RTK's, not ours.
-
-If you build on top of this harness, please give these projects a star — they are the load-bearing dependencies our pipeline assumes, and their authors made them available freely to the community. Any mistake in the way we integrate or describe their work is ours, not theirs.
-
-> For the full rationale on **why each plugin was selected**, **how it integrates inside the harness**, **what breaks if you disable it**, and **alternatives considered**, see the dedicated [External plugins reference](dashboard/public/content/docs/plugins.en.md) — also rendered live at `duk dashboard` → Tech Docs → "External plugins".
-
----
-
-## Release Process
-
-Releases ship through GitHub Actions, not manual `npm publish`.
-
-### Publishing a new version
-
-1. Bump `package.json` version (e.g., `2.0.0-beta.1 → 2.0.0`) and update `CHANGELOG.md`.
-2. Commit + push + tag:
-   ```bash
-   git commit -m "feat!: <summary>"
-   git tag v2.0.0
-   git push origin <branch> --tags
-   ```
-3. Create a GitHub Release pointing at the tag (UI or `gh release create`).
-4. `publish.yml` workflow fires on `release: published`, runs `npm publish --access public`.
-5. `publishConfig.tag` in `package.json` controls dist-tag target (`beta` or `latest`).
-
-### Pre-release vs stable
-
-- Pre-releases use `--tag beta` (default in `publishConfig`). `npx @eltonssouza/development-utility-kit@beta install` pulls them.
-- After validating against real projects: **manually promote** to `latest` via the **Promote npm dist-tag** workflow (GitHub Actions → Run workflow → enter version + target tag).
-
-### Rollback
-
-If a release breaks something, rollback by re-pointing `latest` to the prior stable:
-
-```
-GitHub Actions → Promote npm dist-tag → version=1.0.1, tag=latest
-```
-
-Bad version stays published (npm doesn't allow real deletion past 72h), but no one downloads it via `npx` anymore.
-
-### Required secret
-
-The promote workflow needs a `NPM_TOKEN` repository secret — a **Granular Access Token** with read+write on `@eltonssouza/development-utility-kit`. Generated at https://www.npmjs.com/settings/eltonssouza/tokens.
+## Full documentation
 
----
+See the [GitHub repository](https://github.com/eltonssouza/development-utility-kit) for the complete README, architecture, ADRs, stack packs, and the live dashboard docs.
 
 ## License
 

package/README.npm.md

@@ -0,0 +1,54 @@
+# development-utility-kit
+
+> Meta-skill harness for Claude Code. Stack-agnostic agents, knowledge packs per stack, single-command injection into any project.
+
+[![npm](https://img.shields.io/npm/v/@eltonssouza/development-utility-kit)](https://www.npmjs.com/package/@eltonssouza/development-utility-kit)
+[![license](https://img.shields.io/npm/l/@eltonssouza/development-utility-kit)](https://github.com/eltonssouza/development-utility-kit/blob/main/LICENSE)
+
+CLI binary: `duk` · Node `>=18` · License: MIT
+
+## Install
+
+**As a Claude Code plugin** (recommended — global, every project, nothing written into your repo):
+
+```
+/plugin marketplace add eltonssouza/development-utility-kit
+/plugin install development-utility-kit
+```
+
+**Or inject per-project via npx** (writes `.claude/` + `CLAUDE.md` into the current project, and self-installs the `duk` CLI globally):
+
+```bash
+npx @eltonssouza/development-utility-kit install
+```
+
+> Run `npx … install` from inside a project folder — not from a drive root.
+
+## What you get
+
+- **18 keyword-triggered skills** + **21 stack-agnostic agents** + stack knowledge packs (Java/Spring, TypeScript/Angular, and more)
+- **Front-controller routing** (`project-manager`) + flow governance hook
+- **Full discovery → delivery pipeline** with mandatory TDD and a Senior+ quality gate
+- **Local sub-agent telemetry** + a no-build web dashboard (`duk dashboard`)
+- **Obsidian project brain** (`brain-keeper`)
+
+## `duk` commands
+
+```
+duk new <name>          # scaffold a new project + conversational stack discovery
+duk install             # inject the harness into the current project
+duk install --check-only # preview detected stack + drift, write nothing
+duk sync-all <dir>      # update the harness across many projects
+duk dashboard           # launch the local telemetry + docs dashboard
+duk doctor              # validate environment
+duk lint                # validate harness .claude/ structure
+duk help [command]      # help
+```
+
+## Full documentation
+
+See the [GitHub repository](https://github.com/eltonssouza/development-utility-kit) for the complete README, architecture, ADRs, stack packs, and the live dashboard docs.
+
+## License
+
+MIT