@eltonssouza/development-utility-kit 0.10.1 → 0.12.0

package/README.repo.md

@@ -0,0 +1,447 @@
+# development-utility-kit
+
+> Meta-skill harness for Claude Code. Generic agents by domain, knowledge packs by stack, single-`npx` 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)
+
+CLI binary: `duk` · Node `>=18` · License: MIT
+
+**Install as a Claude Code plugin** (recommended — global, works in every project):
+
+```
+/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):
+
+```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:
+
+- **18 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`.
+
+`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
+
+```
+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)
+```
+
+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
+
+### Two ways to install
+
+| | **Plugin** (recommended) | **npx injection** |
+|---|---|---|
+| Command | `/plugin marketplace add eltonssouza/development-utility-kit` then `/plugin install development-utility-kit` | `npx @eltonssouza/development-utility-kit install` |
+| Scope | Global — every project, every session | Per-project (writes `.claude/` + `CLAUDE.md`) |
+| Lands in | `~/.claude/plugins/` | the project directory |
+| Updates | `/plugin update` (or auto on version bump) | re-run `npx … install` |
+| Per-project stack | declare in a small `CLAUDE.md` `## Project Identity` (or let agents auto-detect) | written into the injected `CLAUDE.md` |
+
+Both deliver the same 18 skills + 21 agents + stack packs. The plugin keeps them global and out of your repo; the npx path injects them into the project (and self-installs `duk` globally). Skills, agents and the flow-governance hook load identically either way.
+
+> **Note on `## Project Identity`:** Claude Code plugins cannot ship a project `CLAUDE.md` (plugin context arrives via skills/agents/hooks, not CLAUDE.md). When you install via the plugin, declare your stack in a short per-project `CLAUDE.md` block so `stack-resolver` picks the right pack — or rely on `detect-stack.js` auto-detection. The npx path still writes the full `CLAUDE.md` for you.
+
+### Brand-new project
+
+```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.
+
+**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
+```
+
+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
+```
+
+---
+
+## `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
+```
+
+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/         # canonical harness sources (also used when dogfooding this repo)
+│   ├── skills/      # 18 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/
+│   ├── hooks/       # flow-guard.js (UserPromptSubmit) + flow-state.js
+│   └── settings.json
+├── .claude-plugin/
+│   └── marketplace.json   # repo is its own marketplace; source → ./plugin
+├── plugin/          # build artifact — lean plugin shipped to /plugin install (skills+agents+stacks+hooks only)
+│   └── .claude-plugin/plugin.json   # generated by scripts/build-plugin.mjs (version tracks package.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
+│   ├── build-plugin.mjs            # assembles plugin/ from .claude/ (--check fails CI on drift)
+│   ├── swap-readme.mjs             # prepack/postpack README ↔ README.npm.md swap
+│   ├── 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.
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -304,12 +304,27 @@ function adoptProject(opts) {
   const destClaude = path.join(subDir, '.claude');
   const destClaudeMd = path.join(subDir, 'CLAUDE.md');
 
+  // Drive-root / system-directory guard.
+  // Prevents EPERM crashes when the user accidentally runs from C:\, D:\, etc.
+  const targetResolved = path.resolve(subDir);
+  const parsed = path.parse(targetResolved);
+  const isDriveRoot = parsed.root === targetResolved + path.sep || parsed.root === targetResolved;
+  const WIN_SYSTEM_PREFIXES = ['\\Windows', '\\Program Files', '\\Program Files (x86)', '\\Users\\Default'];
+  const isSystemDir = process.platform === 'win32' &&
+    WIN_SYSTEM_PREFIXES.some((p) => targetResolved.toLowerCase().startsWith((parsed.root + p.slice(1)).toLowerCase()));
+  if (isDriveRoot || isSystemDir) {
+    process.stderr.write('Error: unsafe install target — cannot install into a drive root or system directory.\n');
+    process.stderr.write(`Target: ${targetResolved}\n`);
+    process.stderr.write('cd into your project folder first, then run:\n');
+    process.stderr.write('  npx @eltonssouza/development-utility-kit install\n');
+    process.exit(1);
+  }
+
   // Item 21 — self-destruction guard.
   // If install runs inside the harness source tree, the backup step would
   // `mv srcClaude → srcClaude.bak`, removing the very source about to be
   // copied. Abort early with a clear message before any destructive op.
   const pkgRootResolved = path.resolve(pkgRoot);
-  const targetResolved = path.resolve(subDir);
   if (targetResolved === pkgRootResolved) {
     process.stderr.write('Error: cannot install harness into its own source tree.\n');
     process.stderr.write(`Target directory equals the harness package root:\n  ${pkgRootResolved}\n`);

package/dashboard/public/content/docs/architecture-overview.en.md

@@ -90,7 +90,7 @@ To force a specific skill, use `/skill <name>` in Claude Code or mention it expl
 - **Front-controller skill**: `project-manager` (ADR-041). Intercepts **every** prompt, enforces the flow order, then dispatches: ROUTE (1 specialist) | ORCHESTRATE (≤5 parallel, shared `run_group_id`) | ESCALATE (`grill-me → analyst → sprint-runner`).
 - **Passive skills**: `caveman` (telegraphic style, always active).
 - **Product skills**: `to-prd`, `to-issues`. Convert artifacts between pipeline stages.
-- **Adoption skills**: `update-template`, `active-project`. Synchronize projects with the latest harness version.
+- **Adoption skills**: `update-template`. Synchronize a project with the latest harness version (terminal equivalents: `duk install`, `duk sync-all` for batch).
 
 The complete skill table lives in [Skills reference](skills-reference).
 
@@ -218,6 +218,23 @@ Both Cowork desktop and Claude Code CLI consume the same `.claude/` from the pro
 
 Rule of thumb: **if Cowork alone covers it, use Cowork**. If you need bash hooks, terminal, or CI automation, use Claude Code CLI on the same project.
 
+## Distribution
+
+The same harness ships through two channels. They deliver identical skills, agents, stack packs and the flow-governance hook — they differ only in *where the files live* and *what scope they cover*.
+
+| | **Plugin** (global) | **npx injection** (vendored) |
+|---|---|---|
+| Install | `/plugin marketplace add eltonssouza/development-utility-kit` → `/plugin install development-utility-kit` | `npx @eltonssouza/development-utility-kit install` |
+| Lands in | `~/.claude/plugins/` | the project's `.claude/` |
+| Scope | every project on the host | one project |
+| In the repo | nothing committed | `.claude/` + `CLAUDE.md` vendored + version-pinned |
+| Updates | `/plugin update` (or auto on version bump) | re-run `npx … install` |
+| Mechanism | `.claude-plugin/marketplace.json` (repo is its own marketplace) points `source` at a lean, build-generated `plugin/` subdir (skills + agents + stacks + hooks only — not the whole repo); `plugin/.claude-plugin/plugin.json` declares `skills`/`agents` and wires hooks via `${CLAUDE_PLUGIN_ROOT}`. `scripts/build-plugin.mjs` regenerates `plugin/` from `.claude/` and CI fails on drift. | `bin/cli.js` copies `.claude/` + merges `CLAUDE.md`, self-installs `duk` globally |
+
+**The one structural constraint.** Claude Code plugins cannot ship a project `CLAUDE.md` — plugin context arrives through skills, agents and hooks, never through a project context file. So the per-project `## Project Identity` block (the 4–6 lines that declare stack / database / domain and let `stack-resolver` pick the right pack) stays a small per-project file when you install via the plugin. The npx path still writes the full `CLAUDE.md` for you, Project Identity included. Either way, `detect-stack.js` can infer most of it from `pom.xml` / `package.json` / `pyproject.toml` / `go.mod`.
+
+Choosing: pick the **plugin** when you want the harness everywhere and out of your repos; pick **npx injection** when you want it committed, pinned, and reproducible inside a specific repo. See the manuals ([quickstart](../manual/quickstart), [existing-project](../manual/existing-project)) for step-by-step install in either model.
+
 ## Telemetry
 
 Subagent telemetry is recorded via the `SubagentStop` hook. Each run carries a `run_group_id` (correlating a parallel orchestration fan) and the project path, powering the dashboard's per-project **Processes** view (ADR-045, Phase A). The flow:

package/dashboard/public/content/docs/cli-reference.en.md

@@ -86,6 +86,10 @@ duk install [--sub <dir>] [--dry-run] [--check-only] [--force]
 
 Injects the harness into the current working directory (or `--sub <dir>` subdirectory). Detects the existing stack from `pom.xml`, `package.json`, `pyproject.toml`, `go.mod`, etc. Preserves any existing `## Project Identity` block in `CLAUDE.md`. Refuses to overwrite local modifications without `--force`.
 
+> **Alternative — install as a plugin.** If you do not want the harness vendored into the repo, install it globally as a Claude Code plugin instead: `/plugin marketplace add eltonssouza/development-utility-kit` then `/plugin install development-utility-kit`. Skills, agents, stack packs and the flow-governance hook load globally with no `.claude/` written into the project. See [architecture-overview](architecture-overview#distribution) for the trade-off. `duk install` remains the path when you want per-project, version-pinned, vendored harness files.
+
+> **Safety guards.** When run via `npx` and `duk` is not yet on PATH, `install` self-installs the CLI globally (`npm install -g`) at the end so subsequent `duk …` calls work. It also refuses to run from a drive root (`C:\`) or a Windows system directory — `cd` into a project folder first.
+
 ### Arguments
 
 (none — operates on the current directory or `--sub <dir>`)
@@ -157,7 +161,7 @@ mv .claude.bak-<timestamp> .claude
 - ADR-018 (CLI redesign, `install → adoptProject`)
 - ADR-028 (workflow), ADR-032 (drift + local/ + opt-in propagation)
 - `update-template` skill — same flow with a preview checkpoint inside chat.
-- `active-project` skill — same flow path-driven, non-interactive (for batch adoption).
+- `duk sync-all <dir>` — non-interactive batch adoption across many projects.
 
 ---
 

package/dashboard/public/content/docs/skills-reference.en.md

@@ -17,7 +17,6 @@ This document covers the 18 official skills of the harness, grouped by purpose.
 | `bootstrap-backend-java` | "scaffolda o backend", "cria backend Java" | `scaffold` | `backend/` Spring Boot 4 + Flyway + compose |
 | `bootstrap-frontend` | "scaffolda o frontend", "cria frontend Angular", "cria frontend Vite" | `scaffold` | `frontend/` Angular 21 or Vite Vanilla |
 | `bootstrap-fullstack` | "cria o esqueleto", "bootstrap fullstack" | `scaffold` | Monorepo `backend/` + `frontend/` + compose |
-| `active-project` | "ativar projeto em `<path>`", "adota o projeto" | `adopt-project.sh` wrapper | Updated `.claude/` + backup |
 | `update-template` | "atualiza o template", "traz as skills novas" | `adopt-project.sh` wrapper | `.claude/` merged with preview |
 | `run-sprint` | "roda a sprint 1", "executa a sprint" | `sprint-runner` → `backend-developer`, `frontend-developer`, `database-engineer`, `gate-keeper` | Code + tests + commit per task |
 | `auto-test-guard` | "roda os testes", "gera os testes", "garante que nada quebrou" | `gate-keeper` | Generated tests + green suite + senior+ gate |
@@ -54,7 +53,7 @@ Reference: **ADR-033** — orchestrate mode fills the fast-lane gap acknowledged
 
 **Prerequisites**: none — it is the front door. It runs the `flow-guard` precondition checks (DISCOVERY/PLAN present for qualified work) before dispatching.
 
-**When NOT to fire**: when a specific skill matches (`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`). Specific skills always win by specificity. For formal sprint execution (with `PLAN_*.md`), use `run-sprint`. For tasks that need a persisted plan or discovery, escalate to `grill-me` → `analyst` first.
+**When NOT to fire**: when a specific skill matches (`run-sprint`, `auto-test-guard`, `prd-ready-check`, `grill-me`, `scaffold`, `pair-debug`, `api-integration-test`, `brain-keeper`, `test-coverage-auditor`, `update-template`, `caveman`). Specific skills always win by specificity. For formal sprint execution (with `PLAN_*.md`), use `run-sprint`. For tasks that need a persisted plan or discovery, escalate to `grill-me` → `analyst` first.
 
 **Mode selection heuristic (deterministic)**: skill counts distinct domains touched (backend, frontend, mobile, database, devops, ux, security, n8n, product, tests, architecture, release). 1 domain → ROUTE. 2–5 domains, independent paths → ORCHESTRATE. >5 or any subtask needs further decomposition → ESCALATE.
 
@@ -174,24 +173,6 @@ Reference: **ADR-033** — orchestrate mode fills the fast-lane gap acknowledged
 
 **When NOT to fire**: project already has backend and frontend (use `run-sprint`); backend-only (`bootstrap-backend-java`) or frontend-only (`bootstrap-frontend`).
 
-### active-project
-
-**PT triggers**: "ativar projeto em `<path>`", "adota o projeto", "aplica o template", "ativa o template em", "sincronizar template no projeto".
-
-**EN triggers**: "/active-project `<path>`", "active project at `<path>`", "activate project `<path>`".
-
-**When to fire**: when the user passes an explicit path and wants one-shot adoption with no preview or checkpoint. Preferred for scripted batches.
-
-**What it does**: one-shot wrapper of `scripts/adopt-project.sh`. Detects type (backend/frontend/fullstack + stack), backs up `.claude/` to `.claude.backup-YYYYMMDD-HHMMSS/`, copies the template, injects the "Identidade deste projeto" block into `CLAUDE.md`, and copies `.claude-version.json`. Supports `--dry-run`, `--force-type=<type>`, `--template=<path>`.
-
-**Delegated agent**: none — calls the script directly via Bash.
-
-**Output / artifacts**: updated `.claude/`; timestamped backup; `CLAUDE.md` with Project Identity filled in; `.claude-version.json`.
-
-**Prerequisites**: project path passed as the first argument.
-
-**When NOT to fire**: to create a new project (use `bootstrap-*`); to update the current project from inside it (use `update-template`, which has preview); to implement features (use `run-sprint`).
-
 ### update-template
 
 **PT triggers**: "atualiza o template", "sync com development-utility-kit", "traz as skills novas", "atualiza as skills", "reimporta o template", "adota o template neste projeto".
@@ -208,7 +189,7 @@ Reference: **ADR-033** — orchestrate mode fills the fast-lane gap acknowledged
 
 **Prerequisites**: being inside a project previously adopted (or about to be adopted).
 
-**When NOT to fire**: to create a new project (`bootstrap-*`); to update project code (`run-sprint`); for batch adoption without preview (`active-project`).
+**When NOT to fire**: to create a new project (`bootstrap-*`); to update project code (`run-sprint`); for batch adoption (`duk sync-all`).
 
 ---
 

package/dashboard/public/content/docs/troubleshooting.en.md

@@ -399,10 +399,10 @@ Each item follows the pattern:
 ### Agents with wrong path
 
 - **Symptom**: agent references missing file in `.claude/agents/`.
-- **Cause**: `active-project` failed partially.
+- **Cause**: a previous `duk install` / `update-template` failed partially.
 - **Solution**:
   ```bash
-  duk active-project <path> --force
+  duk install --force
   ```
 
 ### `settings.json` merge conflicts