@eltonssouza/development-utility-kit 0.11.0 → 0.13.0

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

@@ -64,6 +64,8 @@ duk install --dry-run
 duk install --sub backend
 ```
 
+> **Prefer a global install?** Install the harness as a Claude Code plugin instead — `/plugin marketplace add eltonssouza/development-utility-kit` then `/plugin install development-utility-kit`. Skills and agents load in every project with nothing written into the repo; you keep only a short `## Project Identity` block per project. The npx form above is for vendoring the harness into this repo.
+
 Expected output: creation of `.claude/`, `CLAUDE.md`, `docs/`, and a backup
 `.claude.backup-YYYYMMDD-HHMMSS/` if previous configuration existed.
 
@@ -192,7 +194,6 @@ tests, produce ADRs) and return to the skill, which returns to you.
 | `api-integration-test` | `integration test`, `smoke test`, `bring everything up and test` |
 | `pair-debug` | `let's debug <X>`, `investigate this bug`, `find the root cause`, `why doesn't this work` |
 | `brain-keeper` | `record in the brain`, `update brain`, `daily log`, `save ADR to vault` |
-| `active-project` | `/active-project <path>`, `activate project at <path>` |
 | `update-template` | `update the template`, `sync with development-utility-kit`, `pull the new skills` |
 | `project-manager` | front-controller — intercepts every prompt, enforces flow order, routes/orchestrates |
 | `caveman` | `caveman lite`, `caveman ultra`, `stop caveman` |
@@ -216,7 +217,6 @@ Each one has a dedicated card in the following subsections.
 | `api-integration-test` | You want a real smoke (not unit) | curl report + logs |
 | `pair-debug` | Non-obvious bug, intermittent failure | hypothesis→probe→fix loop |
 | `brain-keeper` | End of sprint/feature, want history | `docs/brain/` daily + feature + ADR |
-| `active-project` | Fast non-interactive adoption by path | `.claude/` installed at path |
 | `update-template` | Pull new skills/agents from harness | Merge into `.claude/` + backup |
 | `caveman` | You want telegraphic answers | Output 65-75% smaller |
 
@@ -527,19 +527,6 @@ save ADR to vault
 - `docs/brain/architecture/tech-debt.md` (updated)
 - MOC (Map of Content) regenerated
 
-### 3.12. `active-project`
-
-**When to use:** fast, non-interactive adoption of an existing project at a
-specific path.
-
-**Triggers:**
-
-```text
-/active-project C:\my-legacy-project
-activate project at C:\my-legacy-project
-adopt the project at C:\old-code
-```
-
 ### 3.13. `update-template`
 
 **When to use:** pull new skills/agents/ADRs from the harness into a
@@ -863,12 +850,13 @@ duk install                   # idempotent, takes automatic backup
 # Edit CLAUDE.md > Project Identity
 ```
 
-### Case 2 — Activate by path (non-interactive)
+### Case 2 — Adopt by path from the terminal
 
-In any terminal with Cowork/Claude Code open, in chat:
+From inside the project directory, run the harness installer:
 
-```text
-/active-project C:\my-legacy-project
+```bash
+cd C:\my-legacy-project
+duk install                   # idempotent, takes automatic backup
 ```
 
 ### Case 3 — Update template in an adopted project
@@ -914,7 +902,7 @@ latest harness version.
 | Telegraphic style | `caveman ultra` |
 | Back to normal | `stop caveman` |
 | Update template | `update the template` |
-| Activate project by path | `/active-project <path>` |
+| Adopt a project by path | `duk install` (from the project dir) |
 
 ---
 
@@ -925,7 +913,7 @@ You have...                              Use...
 ─────────────────────────────────        ──────────────────────────────────
 Empty folder (new project)               scaffold the backend
 Legacy project, first adoption           duk install + edit CLAUDE.md
-Legacy project at a known path           /active-project <path>
+Legacy project, adopt from terminal      duk install
 Vague feature idea                       grill me about <X>
 DISCOVERY done, missing PRD              generate PRD
 PRD done, want issues                    break into issues

package/dashboard/public/content/manual/existing-project.en.md

@@ -16,7 +16,7 @@ running.
 
 - Installing the harness on a project WITHOUT `.claude/`
 - Updating a project that ALREADY has `.claude/` (idempotent)
-- Batch adoption (multiple projects via `/active-project`)
+- Batch adoption (multiple projects via `duk sync-all`)
 - Initial audit: structure, coverage, debt
 - First feature on a legacy codebase with a GREEN baseline
 - Stack migration (Java/Spring/Angular major versions)
@@ -39,6 +39,20 @@ running.
 Scenario: you cloned a legacy repo and want to plug in the harness for the first
 time.
 
+### 2.0 Decide: plugin or npx injection
+
+Two distribution models — pick before you start:
+
+| | **Plugin** (global) | **npx injection** (vendored) |
+|---|---|---|
+| Command | `/plugin marketplace add eltonssouza/development-utility-kit` → `/plugin install development-utility-kit` | `npx @eltonssouza/development-utility-kit install` |
+| Writes into repo | nothing | `.claude/` + `CLAUDE.md` |
+| Scope | every project on the host | this project only |
+| Per-project stack | small `## Project Identity` block in `CLAUDE.md` (or `detect-stack`) | written for you |
+| Best for | "I want it everywhere, out of my repos" | "I want it pinned and committed in this repo" |
+
+If you choose the **plugin**, run the two `/plugin` commands inside Claude Code and skip to §2.6 (just declare `## Project Identity`). The rest of section 2 (§2.1–§2.5) covers the **npx injection** path.
+
 ### 2.1 Preparation
 
 ```bash
@@ -64,7 +78,7 @@ Expected output:
 > Detecting project type...
 ✓ Detected type: fullstack (backend/pom.xml + frontend/angular.json)
 ✓ Backup created at .claude.backup-2026-05-27T14-32-18/ (if .claude already existed)
-✓ .claude/agents/ — 25 agents installed
+✓ .claude/agents/ — 21 agents installed
 ✓ .claude/skills/ — 18 skills installed
 ✓ .claude/settings.json — hooks configured
 ✓ CLAUDE.md — generated/merged preserving Project Identity
@@ -76,8 +90,9 @@ Next step: edit CLAUDE.md → ## Project Identity with the REAL current state of
 
 ### 2.3 Install via global binary
 
-If you've already run `npx @eltonssouza/development-utility-kit install` on the
-host and have `duk` on PATH:
+The first `npx @eltonssouza/development-utility-kit install` now self-installs the
+`duk` CLI globally (`npm install -g`) at the end, so on every project after that
+you can use the shorter binary directly:
 
 ```bash
 cd C:\my-legacy-project
@@ -88,6 +103,9 @@ duk install
 prefer; `update` makes it explicit you're re-injecting on a project that
 already has the harness.
 
+> The installer refuses to run from a drive root (`C:\`) or a Windows system
+> directory — always `cd` into the project folder first.
+
 ### 2.4 Preview without writing
 
 ```bash
@@ -191,30 +209,58 @@ Same triggers as `update-template`. Use whichever vocabulary feels natural.
 
 ## 4. Batch adoption — multiple projects
 
-If you have 5+ legacy repos and want to adopt them all without entering each:
+If you have 5+ legacy repos under one directory and want to adopt them all
+without entering each, use the `duk sync-all` CLI (non-interactive, path-driven).
+It auto-detects each project's type and applies the installed harness:
 
-```text
-/active-project C:/projects/legacy-1
-/active-project C:/projects/legacy-2 --force-type=backend
-/active-project C:/projects/legacy-3 --template=C:/development/tools/development-utility-kit
-/active-project C:/projects/legacy-4 --dry-run
+```bash
+# Preview which projects would be adopted (dry-run is the DEFAULT — writes nothing):
+duk sync-all C:/projects
+
+# Apply to all detected projects:
+duk sync-all C:/projects --apply
+
+# Narrow the batch with filters:
+duk sync-all C:/projects --filter stack:java --apply
+duk sync-all C:/projects --filter age:30d --apply
+
+# Exclude specific projects:
+duk sync-all C:/projects --exclude prod-critical --apply
+```
+
+To adopt a SINGLE project from outside, `cd` into it and run the per-project
+installer (it auto-detects type from `pom.xml` / `package.json`):
+
+```bash
+cd C:/projects/legacy-1
+duk install
 ```
 
-### 4.1 `/active-project` flags
+### 4.1 Relevant `duk` flags
+
+`duk sync-all <dir>`:
+
+- (no flag) — dry-run preview by default, writes nothing
+- `--apply` — actually write `.claude/` + `CLAUDE.md` to each detected project
+- `--filter stack:<lang>` / `--filter age:<N>d` / `--filter harness-version:<X>` —
+  narrow which projects are included
+- `--exclude <name>` — skip specific projects
+
+`duk install` (run from the project directory):
+
+- `--check-only` — compare local vs latest harness without writing
+- `--dry-run` — preview the install without writing
+- `--sub <dir>` — install into a subfolder of the current repo
 
-- `--dry-run` — preview, writes nothing
-- `--force-type=<backend|frontend|fullstack|mobile>` — force type when
-  auto-detect gets it wrong (e.g. backend with `package.json` for build tools
-  but actually Java)
-- `--template=<path>` — use an alternate template path (local forks, pending
-  upstream fix)
-- `--skip-brain` — don't provision `docs/brain/`
+> Type is auto-detected from project files (`pom.xml`, `package.json`, etc.);
+> there is no manual `--force-type` for the batch flow. The template used is
+> always the installed harness — no alternate `--template` path.
 
 ### 4.2 Fast-lane vs interactive
 
-| Skill | Mode | When to use |
+| Entry point | Mode | When to use |
 |---|---|---|
-| `active-project` | Non-interactive, path-driven | Batch, multiple projects, CI |
+| `duk sync-all` | Non-interactive, path-driven | Batch, multiple projects, CI |
 | `update-template` | Interactive, prompt-driven | Single project, manual validation |
 | `duk install` (CLI) | Non-interactive, CWD-driven | Local, first contact |
 
@@ -562,7 +608,7 @@ All trigger the `update-template` agent (haiku). Result identical to CLI.
 
 | I want to... | Type |
 |---|---|
-| Adopt project without .claude/ | `duk install` (terminal) OR `/active-project <path>` (chat) |
+| Adopt project without .claude/ | `duk install` (terminal) OR `update-template` (chat) |
 | Update template | `duk install` (terminal) OR `update the template` (chat) |
 | Compare with official template | `auditor compares .claude structure with official template` |
 | Audit coverage | `audit the tests` |
@@ -574,7 +620,7 @@ All trigger the `update-template` agent (haiku). Result identical to CLI.
 | First feature on legacy | `run the tests` → `grill me about <X>` |
 | Bug on legacy | `let's debug <X>` |
 | PRD-ready check | `is this ready for production?` |
-| Batch adoption | `/active-project <path>` repeated |
+| Batch adoption | `duk sync-all <dir> --apply` |
 | Remember state | `remember that the project is on <stack>` |
 | Register feature/ADR/debt | `register in the brain` |
 | Debt-payment sprint | `run sprint 0` (after tech-lead plan) |
@@ -583,7 +629,7 @@ All trigger the `update-template` agent (haiku). Result identical to CLI.
 
 ```text
 .claude/ absent in the project?
-  → duk install (CLI) or /active-project <path> (chat batch)
+  → duk install (CLI) or update-template (chat)
 
 .claude/ present but outdated?
   → duk install (idempotent) OR "update the template"
@@ -604,7 +650,7 @@ About to start a new feature?
   → Gate RED? → pay debt first
 
 Several projects to adopt at once?
-  → "/active-project <path>" in batch (non-interactive)
+  → "duk sync-all <dir> --apply" (non-interactive batch)
 
 Obscure/intermittent bug on legacy?
   → "let's debug <X>" (pair-debug, hypothesis-driven)
@@ -707,10 +753,11 @@ conflict on the next merge.
 | Obsidian vault without `MOC.md` | New vault, brain-keeper hasn't run yet | `register in the brain` creates MOC and indices |
 | `settings.json` customizations lost | Merge overwrote on update | Restore from `.claude.backup-<date>/settings.json` |
 | Agents with old path after update | Incomplete backup | `duk install --force` or remove `.claude/` and reinstall |
-| `npx @eltonssouza/development-utility-kit install` fails with EACCES | Permission on target directory | Run as admin OR `--path <dir-with-permission>` |
+| `npx @eltonssouza/development-utility-kit install` fails with EACCES | Permission on target directory | `cd` into a directory you own and re-run, or run the shell as admin |
+| `npx … install` aborts with "unsafe install target" | Ran from a drive root (`C:\`) or system dir | `cd` into the project folder first — the installer refuses drive roots / system dirs |
 | `duk install --sub <folder>` doesn't detect type | Subfolder without `pom.xml`/`package.json` at root | `--force-type=<backend\|frontend>` |
 | Dashboard 4242 won't start | Port in use or Node < 18 | `node -v` and free the port |
-| `/active-project` doesn't recognize path | Path with spaces or backslash | Use forward slash: `C:/projects/legacy-1` |
+| `duk install` / `duk sync-all` doesn't recognize path | Path with spaces or backslash | Use forward slash: `C:/projects/legacy-1` |
 
 ## 16. Active hooks after `duk install`
 

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

@@ -49,6 +49,8 @@ npx @eltonssouza/development-utility-kit install
 
 Idempotent: runs `git pull` if the repository already exists.
 
+> **Prefer a global install?** Install the harness as a Claude Code plugin instead — `/plugin marketplace add eltonssouza/development-utility-kit` then `/plugin install development-utility-kit`. Skills and agents load in every project with nothing written into the repo; you keep only a short `## Project Identity` block per project. The npx form is for vendoring the harness into this repo.
+
 ### Step 2 — Create (or enter) the frontend project
 
 ```bash
@@ -309,39 +311,56 @@ The harness exposes skills that trigger by **keyword** in Claude Code/Cowork con
 
 ---
 
-## 5. External **Impeccable** skill — visual refinement
+## 5. External **Impeccable** skill — frontend design gate
 
 > Impeccable does not ship with `development-utility-kit`. It's an independent skill by Paul Bakaus. **For frontend it is highly recommended.**
 
+### How it fires (ADR-048)
+
+`project-manager` is the **front-controller** and owns the design gate. **Whenever frontend/ux work is in scope, it offers impeccable** (mandatory offer; you choose). On "Sim" it runs three ordered gates and then resumes control:
+
+```
+front detectada → PM pergunta "usar impeccable?"
+  └─ Sim:
+       1. [terminal, no projeto]  npx skills add pbakaus/impeccable   (só se ausente)
+       2. [claude code]           /impeccable teach                   (analisa o projeto)
+       3. [claude code]           /impeccable <verbo>                 (polish / audit / …)
+       → project-manager retoma a orquestração
+```
+
+The offer is mandatory, the use is yours — same gating philosophy as `grill-me`. `project-manager` never auto-runs it and never abdicates control (impeccable is a sub-routine, not a takeover).
+
 ### Origin
 
 - Author: Paul Bakaus
 - Repo: `github.com/pbakaus/impeccable`
 
-### Installation
+### Installation (gate 1 — terminal, per-project)
 
 ```bash
 npx skills add pbakaus/impeccable
 ```
 
-Installs as an additional Claude Code skill. The `/impeccable *` commands become available in chat.
+Installs into the **selected project's** `.claude/skills/` — the `/impeccable *` commands then become available in that project's Claude Code chat. `project-manager` runs this automatically when you accept the offer and impeccable is not yet present.
 
-### Available commands
+### Available commands (gates 2 & 3 — Claude Code)
 
 | Command | What it does |
 |---|---|
+| `/impeccable teach` | **Run first.** Analyzes the project (stack, tokens, existing patterns) so impeccable acts in context. Alias of `init`. |
+| `/impeccable shape` | Builds/redesigns a UI from scratch. |
 | `/impeccable polish` | Refines fine details: spacing, alignment, visual hierarchy, microinteractions. |
-| `/impeccable harden` | Hardens visual robustness against edge cases: overflow, long text, RTL, 200% zoom, dark mode. |
 | `/impeccable audit` | Full scan: typography, color, layout, WCAG contrast, hierarchy. Produces report. |
-| `/impeccable typeset` | Refines typography (scale, line-height, tracking, leading). |
-| `/impeccable colorize` | Refines palette and ensures WCAG AA/AAA contrast. |
-| `/impeccable layout` | Reviews hierarchy, spacing, density, grid alignment. |
+| `/impeccable critique` | Heuristic critique of an existing UI. |
+| `/impeccable harden` | Hardens visual robustness against edge cases: overflow, long text, RTL, 200% zoom, dark mode. |
+| `/impeccable clarify` · `colorize` · `animate` · `distill` | Targeted refinements (copy clarity, palette, motion, simplification). |
 
 ### When to use
 
-- **After** `frontend-developer` implements a screen.
+- When `project-manager` offers it on frontend work and you accept (the normal path).
+- **After** `frontend-developer` implements a screen, or standalone visual refactor.
 - **Before** `prd-ready-check`.
-- In short cycle: `polish` → re-run `jest-axe` → `harden` → re-run Lighthouse → `audit`.
+- Always run `/impeccable teach` once per project before the action verbs.
 
 ### When **NOT** to use Impeccable
 

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

@@ -241,7 +241,6 @@ conversational.
 | `prd-ready-check` | `is it production-ready?`, `DoD` | GO / NO-GO |
 | `pair-debug` | `let's debug <X>`, `investigate this bug` | Hypothesis loop |
 | `brain-keeper` | `record in brain`, `update the brain` | `docs/brain/` vault |
-| `active-project` | `/active-project <path>`, `adopt project at <path>` | Non-interactive adoption |
 | `update-template` | `update the template` | Sync `.claude/` + `CLAUDE.md` (merge) |
 | `project-manager` | front-controller | Intercepts all; ROUTE / ORCHESTRATE / ESCALATE |
 
@@ -333,17 +332,6 @@ Provisions / updates `docs/brain/`:
 All in Obsidian (vault) format, with `[[wiki]]` links, `#feature`, `#bug`,
 `#adr` tags, and a MOC (Map of Content) per area.
 
-### 5.11. `active-project`
-
-Non-interactive adoption of a legacy project:
-
-```text
-> "/active-project C:\projects\legacy-fullstack"
-```
-
-Equivalent to the fast lane of `update-template` when you want to skip the
-wizard.
-
 ### 5.12. `update-template`
 
 Syncs `.claude/` + `CLAUDE.md` with the latest harness release. The merge
@@ -360,7 +348,12 @@ Front-controller (ADR-041): it intercepts every prompt, enforces the flow order,
 typographic polish**. Especially relevant on the frontend side of a
 fullstack project.
 
-**Install** (once per project):
+> **How it fires (ADR-048):** `project-manager` offers impeccable whenever
+> frontend/ux work is in scope (mandatory offer, your choice). On "Sim" it
+> installs if absent, runs `/impeccable teach` (analyzes the project), then the
+> action verb — and resumes control. See the [frontend manual](frontend) §5.
+
+**Install** (gate 1 — once per project, terminal):
 
 ```bash
 npx skills add pbakaus/impeccable
@@ -891,6 +884,8 @@ duk install --dry-run
 non-destructive merge and creates `CLAUDE.md.bak-<timestamp>` before
 touching anything.
 
+> **Prefer a global install?** Install the harness as a Claude Code plugin instead — `/plugin marketplace add eltonssouza/development-utility-kit` then `/plugin install development-utility-kit`. Skills and agents load in every project with nothing written into the repo; you keep only a short `## Project Identity` block per project. The npx form above is for vendoring the harness into this repo.
+
 Edit `CLAUDE.md`:
 
 ```markdown
@@ -910,10 +905,11 @@ In chat:
 > "migrate to Spring Boot 4 + Angular 21"   (optional)
 ```
 
-For non-interactive adoption:
+For non-interactive adoption, run the `duk` CLI from inside the project (or
+trigger `update-template` in chat):
 
-```text
-> "/active-project C:\projects\legacy-fullstack"
+```bash
+duk install   # run from C:\projects\legacy-fullstack
 ```
 
 ---
@@ -1157,7 +1153,7 @@ Big table, ordered by intent.
 |---|---|---|
 | New monorepo from scratch | `scaffold the monorepo` | `bootstrap-fullstack` |
 | Adopt existing project | `duk install` (CLI) + `auditor, compare structure` | `update-template` + `auditor` |
-| Non-interactive adoption | `/active-project C:\projects\X` | `active-project` |
+| Non-interactive adoption | `duk install` (per project) / `duk sync-all` (batch) | `duk` CLI |
 | Idea discovery | `grill me about <X>` | `grill-me` |
 | Generate PRD | `generate PRD` | `to-prd` |
 | PRD into issues | `break into issues` | `to-issues` |

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

@@ -49,6 +49,8 @@ duk install
 # ✓ scripts/hooks/ installed
 ```
 
+> **Prefer a global install?** Install the harness as a Claude Code plugin instead — `/plugin marketplace add eltonssouza/development-utility-kit` then `/plugin install development-utility-kit`. Skills and agents load in every project with nothing written into the repo; you keep only a short `## Project Identity` block per project. The `duk install` form above vendors the harness into this repo.
+
 Edit `CLAUDE.md` under the `Project Identity` section:
 
 ```markdown
@@ -140,7 +142,6 @@ Mobile uses the harness's general skill catalog. There is no mobile-specific ski
 | `pair-debug` | "let's debug X", "investigate this bug" | Hypothesis -> probe -> confirm loop |
 | `prd-ready-check` | "PRD ready?", "DoD" | GO / NO-GO |
 | `brain-keeper` | "record in brain", end of PLAN | Notes in `docs/brain/` |
-| `active-project` | "/active-project <path>" | Fast-lane adoption |
 | `update-template` | "update template" | Sync `.claude/` + `CLAUDE.md` |
 | `caveman` | always-on, "stop caveman" | Telegraphic output |
 
@@ -834,4 +835,4 @@ Check:
 - [Backend manual](./backend) — Java 25 + Spring Boot 4
 - [Frontend manual](./frontend) — Angular 21
 - [Fullstack manual](./fullstack) — backend + frontend monorepo
-- [Existing project manual](./existing-project) — adoption via active-project
+- [Existing project manual](./existing-project) — adoption via update-template / duk install

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

@@ -15,7 +15,27 @@ 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.
+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 — there is no `duk run` command that talks to an LLM. The LLM client (Claude Code / Cowork) reads the skills and invokes the agents.
+
+---
+
+## Two ways to install
+
+Pick one:
+
+- **Plugin (recommended)** — installs globally into `~/.claude/plugins/`, available in every project, nothing written into your repo. Best when you want the harness everywhere without vendoring it.
+- **npx injection** — writes `.claude/` + `CLAUDE.md` into a specific project (Paths A/B below). Best when you want the harness vendored into the repo and version-pinned per project.
+
+Both deliver the same skills, agents, stack packs and the flow-governance hook.
+
+### Path 0 — Install as a Claude Code plugin (30 seconds)
+
+```
+/plugin marketplace add eltonssouza/development-utility-kit
+/plugin install development-utility-kit
+```
+
+Run those two in Claude Code. Every skill and agent is now available in any project you open — no per-project setup. Declare your stack in a short `## Project Identity` block in the project's `CLAUDE.md` (or let `detect-stack` infer it) so `stack-resolver` picks the right pack. Plugins cannot ship a project `CLAUDE.md`, so that small block stays per-project.
 
 ---
 
@@ -150,6 +170,8 @@ If you adopt the harness on a real project and ship something with it, please co
 | Symptom | Likely cause | Fix |
 |---|---|---|
 | `duk doctor` reports Node < 18 | Old Node installed | Install Node 18+ from nodejs.org or your package manager |
+| `npx … install` aborts with "unsafe install target" | You ran it from a drive root (`C:\`) or a system directory | `cd` into your project folder first, then re-run. The installer refuses drive roots / system dirs to avoid writing `C:\CLAUDE.md` |
+| `duk` not found after `npx … install` | Older versions did not self-install the CLI | `npx … install` now runs `npm install -g` automatically; if it still fails, run `npm install -g @eltonssouza/development-utility-kit` once. (Plugin install does not need `duk` on PATH at all.) |
 | `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` (front-controller) 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) |

package/dashboard/test/sprint2.test.js

@@ -466,11 +466,6 @@ describe('T-012: manual content — existing project adoption scenario', () => {
     }
   });
 
-  test('existing-project.pt.md mentions active-project', () => {
-    const content = fs.readFileSync(ptFile, 'utf8');
-    assert.ok(content.includes('active-project'), 'Missing active-project mention in existing-project.pt.md');
-  });
-
   test('existing-project.pt.md mentions update-template', () => {
     const content = fs.readFileSync(ptFile, 'utf8');
     assert.ok(content.includes('update-template'), 'Missing update-template mention in existing-project.pt.md');
@@ -486,11 +481,6 @@ describe('T-012: manual content — existing project adoption scenario', () => {
     assert.ok(content.includes('Project Identity'), 'Missing Project Identity mention in existing-project.pt.md');
   });
 
-  test('existing-project.en.md mentions active-project', () => {
-    const content = fs.readFileSync(enFile, 'utf8');
-    assert.ok(content.includes('active-project'), 'Missing active-project mention in existing-project.en.md');
-  });
-
   test('existing-project.en.md mentions update-template', () => {
     const content = fs.readFileSync(enFile, 'utf8');
     assert.ok(content.includes('update-template'), 'Missing update-template mention in existing-project.en.md');

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@eltonssouza/development-utility-kit",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "npx installer for the development-utility-kit harness",
   "bin": {
     "duk": "bin/cli.js"
   },
+  "scripts": {
+    "build:plugin": "node scripts/build-plugin.mjs",
+    "build:plugin:check": "node scripts/build-plugin.mjs --check",
+    "prepack": "node scripts/swap-readme.mjs pre",
+    "postpack": "node scripts/swap-readme.mjs post"
+  },
   "files": [
     "bin",
     "bin/lib",

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

@@ -1,131 +0,0 @@
----
-name: active-project
-description: Use to ACTIVATE/ADOPT a project to the `development-utility-kit` template in ONE shot — accepts the project path as the FIRST argument and runs `scripts/adopt-project.sh` directly without preview/checkpoint. Triggers when the user types `/active-project <path>` or says "active project at <path>", "activate project <path>", "ativar projeto", "adota o projeto X", "aplica o template no projeto Y", "ativar template em <path>". Same end-result as `update-template`, but path-driven and non-interactive — preferred for scripted batch adoptions. Supports `--dry-run`, `--force-type=<backend|frontend|fullstack>`, `--template=<path>`. Do NOT use to develop features (use run-sprint), scaffold empty projects (use scaffold), or update the current project's template from inside it (use update-template). PT triggers: 'ativar projeto', 'adota o projeto', 'aplica o template', 'ativa o template em', 'ativar projeto em', 'sincronizar template no projeto'.
-tools: Read, Write, Glob, Grep, Bash(bash:*), Bash(git:*)
-model: sonnet
----
-
-# Active Project — Adopt a project to the template (path-driven, non-interactive)
-
-Always reply in **Brazilian Portuguese**.
-
----
-
-## 1. When it triggers
-
-Exact invocations:
-- `/active-project /path/to/project`
-- `/active-project /path/to/project --dry-run`
-- `/active-project /path/to/project --force-type=fullstack`
-- `/active-project /path/to/project --template=/alt/template`
-
-Natural-language equivalents:
-- "ativar projeto em `/path`"
-- "adota o projeto em `/path` com template fullstack"
-- "aplica o template no projeto X em modo dry-run"
-
-If the user asks **without a path**, ask for it before running anything.
-
----
-
-## 2. What it does
-
-Single-shot wrapper around `scripts/adopt-project.sh`:
-
-1. Detects project type (`backend | frontend | fullstack` + stack `angular | vite-vanilla`) from `backend/pom.xml`, `frontend/angular.json`, `frontend/vite.config.*`.
-2. Backs up the existing `.claude/` to `.claude.backup-YYYYMMDD-HHMMSS/`.
-3. Copies the template `.claude/` into the project, preserving local files outside the template.
-4. Copies the template `CLAUDE.md` and appends the **"Identidade deste projeto"** block (project name, type, stack, adoption date).
-5. Copies `.claude-version.json` and flags as outdated when versions diverge.
-6. Reports backup paths, detected type, and any `[WARN]`/`[ERROR]` from the script.
-
-This is the **fast path** of `update-template`: no preview, no checkpoint, no confirmation.
-
----
-
-## 3. Difference from `update-template`
-
-| | `active-project` (this) | `update-template` |
-|---|---|---|
-| Path | First positional ARG | Current working directory |
-| Preview/checkpoint | NO (direct execution) | YES (interactive) |
-| Best for | Scripts, batch adoptions | Manual flow inside Claude Code with confirmation |
-| Idempotent | YES (same as adopt-project.sh) | YES |
-
-Both ultimately call `scripts/adopt-project.sh` — they share the engine.
-
----
-
-## 4. Procedure
-
-1. **Parse the user message** to extract:
-   - PROJECT_PATH (first non-flag argument; absolute path expected)
-   - FLAGS (`--dry-run`, `--force-type=<tipo>`, `--template=<path>`)
-2. **Validate** that PROJECT_PATH exists:
-   ```bash
-   [ -d "<PROJECT_PATH>" ] || echo "[ERROR] Pasta nao existe: <PROJECT_PATH>"
-   ```
-   If it does not exist, STOP and tell the user.
-3. **Locate the template** (default: `C:\development\tools\development-utility-kit` on Windows, `~/workspace/tools/development-utility-kit` on Linux/Mac). Override with `--template` if provided.
-4. **Run** via the `terminal` tool:
-   ```bash
-   bash <TEMPLATE>/scripts/adopt-project.sh "<PROJECT_PATH>" [FLAGS]
-   ```
-5. **Capture full stdout/stderr** and surface it to the user in **PT-BR**, including:
-   - Detected (or forced) type
-   - Backup paths created
-   - `[OK]/[WARN]/[ERROR]` messages from the script
-   - The final "Adoption/update finished" block
-   - Whether the project was flagged as outdated (template/project version mismatch)
-6. If the script reports `[WARN] Could not detect project type`, suggest re-running with `--force-type=<backend|frontend|fullstack>`.
-
----
-
-## 5. Quick Reference
-
-| Case | Command |
-|---|---|
-| Adopt a fullstack project | `bash adopt-project.sh /path/to/project` |
-| Force the type (no code yet) | `bash adopt-project.sh /path --force-type=fullstack` |
-| Simulate without applying | `bash adopt-project.sh /path --dry-run` |
-| Alternative template | `bash adopt-project.sh /path --template=/other/template` |
-
----
-
-## 6. Pitfalls
-
-- **Path does not exist** → script aborts with `[ERROR] Folder does not exist`. Validate before invoking.
-- **No `backend/` or `frontend/`** → script fails with `[WARN] Could not detect project type`. Use `--force-type=<tipo>` for projects without code yet.
-- **Path with spaces** → always wrap in quotes when building the command.
-- **Already adopted** → script silently creates a backup (`.claude.backup-*`). Mention this to the user.
-- **Output verbosity** → if the user requests "mostre tudo" / "literal output", echo the captured stdout verbatim (do NOT summarize).
-
----
-
-## 7. Verification
-
-After applying (no `--dry-run`):
-
-1. `<PROJECT_PATH>/.claude/agents`, `<PROJECT_PATH>/.claude/commands`, `<PROJECT_PATH>/.claude/skills` exist.
-2. `<PROJECT_PATH>/CLAUDE.md` contains the block `## Identidade deste projeto`.
-3. `<PROJECT_PATH>/.claude-version.json` matches the template's version (otherwise report as outdated).
-4. The script printed `Adoption/update finished: <project-name>`.
-
----
-
-## 8. Inviolable rules
-
-1. NEVER infer or invent a `PROJECT_PATH` from context — if the user did not provide one, ASK.
-2. NEVER execute without `--dry-run` if the user explicitly asked for a simulation.
-3. ALWAYS surface `[WARN]`/`[ERROR]` lines verbatim — do not omit them in the summary.
-4. ALWAYS report the backup paths so the user can recover.
-5. If invoked non-interactively (e.g. from a script), prefer non-blocking mode (no interactive prompts).
-
----
-
-## 9. References
-
-- Engine script: `scripts/adopt-project.sh`
-- Interactive sibling: [`update-template`](../update-template/SKILL.md)
-- Bootstrap (different purpose — creates new projects): [`scaffold`](../scaffold/SKILL.md)
-- Canonical project directory: `C:\development\source\projects\<name>\`