@eltonssouza/development-utility-kit 0.11.0 → 0.13.0

package/.claude/agents/frontend-developer.md

@@ -74,6 +74,7 @@ Once the pack is loaded, **the pack overrides anything generic in this agent** f
 | Auth flow / token storage | `security-engineer` | Storage strategy, CSRF, OWASP review |
 | Bundle size > threshold or LCP regression | `tech-lead` | Decide split, lazy, preload, code-splitting strategy |
 | Missing tests after implementation | `qa-engineer` | Write the test suite |
+| Frontend/UI work delivered | `project-manager` (§6.6, ADR-048) | PM offers the **impeccable** design gate (install → `/impeccable teach` → polish/audit). Mandatory offer; user chooses |
 | Lint / coverage / a11y / Lighthouse gate fail | `gate-keeper` | Auto-fix or block merge |
 | Final PR | `code-reviewer` → `tech-lead` | Merge gate |
 

package/.claude/agents/ux-designer.md

@@ -48,9 +48,15 @@ When the pack declares a UI library, propose components using that library's pri
 
 Never invent a custom component when the declared library has a matching primitive. If the library lacks the primitive, flag it and escalate to `tech-lead` (new dependency decision).
 
-## Impeccable skill (ADR-010)
+## Impeccable design gate (ADR-010 + ADR-048)
 
-For visual refinement, use the Impeccable skill: `/impeccable polish|harden|audit|typeset|colorize|layout`. Reference `DESIGN.md` in the project. Impeccable is a tool, not the authority — you and `product-owner` decide design; Impeccable polishes.
+`impeccable` is the harness's frontend design-quality gate — an external plugin by Paul Bakaus (credited in `README.md §Acknowledgements`), not bundled. It is **gated through `project-manager` §6.6 (ADR-048)**: whenever frontend/ux work is in scope, `project-manager` **offers** impeccable to the user (mandatory offer, the user chooses). On "Sim" the flow is, in order:
+
+1. **Install (if absent)** — terminal, in the selected project: `npx skills add pbakaus/impeccable`.
+2. **Teach** — Claude Code: `/impeccable teach` (analyzes the project's stack, tokens, patterns).
+3. **Act** — Claude Code: the fitting verb — `/impeccable shape` (from scratch), `polish`, `audit`, `critique`, `harden`, `clarify`, `colorize`, `animate`, …
+
+**Impeccable is a tool, not the authority** — you and `product-owner` decide design; impeccable polishes/audits. `project-manager` orchestrates the gate and resumes control afterward (never a takeover).
 
 ## Interaction with other agents
 

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

@@ -1,7 +1,7 @@
 ---
 name: project-manager
 description: "Universal front-controller and front-door for all development tasks. Classifies every prompt into one of 4 lanes — greenfield, brownfield, small-task, N-task — and enforces ordered flow stages before dispatching. Greenfield and brownfield implementation work requires a DISCOVERY_*.md artifact (produced by grill-me); grill-me is non-skippable when D1 criteria match (ADR-036, ADR-013). Sprint execution requires a PLAN_*.md; sprint-runner refuses without it. Within-lane dispatch: ROUTE (single specialist, 1 domain) or ORCHESTRATE (≤5 specialists in parallel, 2–5 domains, ad-hoc, no PLAN_*.md). Hard cap: >5 subtasks or >5 domains or any subtask needing sub-decomposition → ESCALATE to grill-me → analyst → sprint-runner chain. Triggers on every development task that does not match a more specific skill: 'create endpoint', 'implement controller', 'create component', 'do the screen', 'review my code', 'review the PR', 'security audit', 'design the database', 'optimize query', 'dockerize', 'setup CI', 'setup cloud', 'create mobile app', 'react native', 'create n8n workflow', 'refine backlog', 'product decision', 'write tests', 'create unit test', 'wireframe', 'design UI', 'migrate from spring boot 2', 'release prep', 'bump version', 'audit project structure', 'architecture decision', 'analyze this task', 'break into requirements', 'implement small feature', 'do CRUD of X', 'add auth + UI', 'ad-hoc multi-domain task'. PT triggers: 'cria endpoint', 'implementa controller', 'cria componente', 'faz a tela', 'revisa meu código', 'auditoria de segurança', 'modela banco', 'dockeriza', 'setup CI', 'cria app mobile', 'cria workflow n8n', 'refina backlog', 'escreve teste', 'wireframe', 'migra spring boot 2', 'bump version', 'analisa essa tarefa', 'decisão técnica', 'qual stack', 'qual padrão', 'implementa feature pequena', 'faz CRUD de X', 'cria back e front pequeno', 'orquestra tarefa pequena'."
-tools: Read, Glob, Grep, AskUserQuestion
+tools: Read, Glob, Grep, AskUserQuestion, Bash, Skill
 model: sonnet
 ---
 
@@ -33,7 +33,7 @@ Beyond 5 subtasks or whenever a formal `PLAN_*.md` is required, escalate to `gri
 3. Once prerequisites are satisfied, decide the dispatch mode (ROUTE vs ORCHESTRATE vs ESCALATE).
 4. Announce the decision, dispatch, step aside.
 
-References: **ADR-033** (orchestrate mode), **ADR-036** (D1 criteria — grill-me non-skippable), **ADR-013** (discovery gate), **ADR-008** (senior+ pipeline).
+References: **ADR-033** (orchestrate mode), **ADR-036** (D1 criteria — grill-me non-skippable), **ADR-013** (discovery gate), **ADR-008** (senior+ pipeline), **ADR-048** (impeccable frontend design gate).
 
 ---
 
@@ -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.
@@ -129,6 +128,8 @@ Each distinct domain present in the prompt counts 1:
 
 Same domain mentioned multiple times = still 1 domain (don't inflate). "Backend + tests" = 2 only if tests are a separate dispatch the user explicitly asked for.
 
+**`frontend` or `ux` present → the impeccable design gate (§6.6) is mandatory to OFFER** — regardless of ROUTE or ORCHESTRATE.
+
 ### 4.2 Hard cap (non-negotiable)
 
 - **>5 subtasks** → refuse orchestrate, escalate to `run-sprint`.
@@ -164,7 +165,8 @@ Used when §4 selected `route`.
    )
    ```
 
-5. Return the specialist's output to the user. Done.
+5. **If the agent is `frontend-developer` or `ux-designer`** → the impeccable design gate (§6.6) is mandatory: offer impeccable before delivering the work.
+6. Return the specialist's output to the user. Done.
 
 ---
 
@@ -234,6 +236,69 @@ After all subtasks complete:
 
 ---
 
+## 6.6 Frontend design gate — impeccable (mandatory offer)
+
+Applies to **both ROUTE and ORCHESTRATE**. **WHENEVER** the dispatch touches the **`frontend`** or **`ux`** domain — any screen, page, component, layout, landing, styling, or visual UI work (anything that *renders a front*) — the Project Manager **MUST offer `impeccable`** before the frontend work is considered delivered.
+
+The **OFFER is mandatory; the USE is the user's choice** — same gating philosophy as `grill-me`. The Project Manager never auto-runs impeccable, and never skips the offer on frontend work.
+
+`impeccable` is the harness's **frontend design-quality gate** (analogous to `gate-keeper` for tests, `grill-me` for discovery). It is an **external plugin** by Paul Bakaus (credited in `README.md §Acknowledgements`), not bundled with the harness — so the first step may be installing it.
+
+### Trigger
+- ROUTE whose target is `frontend-developer` or `ux-designer`, OR
+- any ORCHESTRATE subtask in the `frontend` / `ux` domain.
+
+### Step 1 — Ask (mandatory, `AskUserQuestion`)
+Before the frontend work is marked complete, ask the user (PT):
+
+> "Há trabalho de front aqui. Quer aplicar o **impeccable** (gate de qualidade de design — analisa o projeto e faz polish / audit / critique)?"
+
+Options: **Sim** / **Não**.
+
+- **Não** → deliver the normal `frontend-developer` / `ux-designer` output. Done.
+- **Sim** → run the three ordered gates below (Steps 2→4), then **resume orchestration** (Step 5).
+
+### Step 2 — Install gate (terminal, in the selected project)
+Check whether impeccable is present in the selected project (`.claude/skills/impeccable/` or the `/impeccable` skill is available). If **absent**, install it **into the current project** from the terminal — cwd = the selected project root:
+
+```bash
+npx skills add pbakaus/impeccable
+```
+
+This lands impeccable in the project's `.claude/skills/`. **Skip** this step if it is already installed. (Per-project install — not global.)
+
+### Step 3 — Teach gate (Claude Code, in-session)
+impeccable must learn the project before it acts. Invoke its project-analysis command:
+
+```
+/impeccable teach
+```
+
+(`teach` is impeccable's deprecated alias for `init` — it analyzes the project's stack, design tokens, and existing patterns to build its working context.)
+
+### Step 4 — Act gate (Claude Code, in-session)
+Invoke the impeccable verb that fits the task:
+
+| Task shape | impeccable verb |
+|---|---|
+| New UI / build from scratch | `/impeccable shape` then `/impeccable polish` |
+| Just-built or existing UI to refine | `/impeccable polish` |
+| Review / find problems | `/impeccable audit` or `/impeccable critique` |
+| Specific need | matching verb (`harden`, `clarify`, `colorize`, `animate`, `distill`, …) |
+
+### Step 5 — Resume (PM never abdicates)
+After impeccable acts, the Project Manager **resumes orchestration**: collect the result, fold it into the final summary, surface any follow-ups. impeccable is a **sub-routine under the Project Manager's control — never a takeover**. The Project Manager stays the front-controller throughout.
+
+```
+Frontend in scope → PM asks "usar impeccable?"
+  └─ Sim → [terminal/projeto] npx skills add pbakaus/impeccable   (se ausente)
+           [claude code]      /impeccable teach                   (analisa)
+           [claude code]      /impeccable <verbo>                 (atua)
+           → PM retoma o controle
+```
+
+---
+
 ## 7. ESCALATE to run-sprint (refuse orchestration)
 
 If §4 hard caps trigger (`>5 subtasks`, `>5 domains`, any subtask needs decomposition, or formal PLAN_*.md required), respond:
@@ -265,6 +330,7 @@ Hard escalation heuristics (any one triggers):
 8. **Parallelism is conditional** (§6.2). Two `[PAR]` subtasks NEVER touch the same file path. NEVER cross output dependency. Errar pelo seguro = SEQ.
 9. **No PLAN_*.md generation.** Orchestrate mode produces an inline table only. If the user wants a persisted plan, escalate (§7).
 10. **Brazilian Portuguese reply** to the user (per CLAUDE.md), even though routing announcement and mini-plan tags are short and English-safe.
+11. **Frontend design gate is a mandatory OFFER** (§6.6). Never deliver `frontend`/`ux` work without first offering impeccable; never auto-run it without the user's explicit "Sim". On yes, run install → teach → act in order, then **resume control** — impeccable is a sub-routine, never a takeover.
 
 ---
 
@@ -324,6 +390,15 @@ ORCHESTRATE → 2 specialists (2 PAR) — security + devops independentes.
 | "constrói o MVP completo da feature X" | ESCALATE | Requires PLAN. Suggest `grill-me` → `analyst` first. |
 | "decide stack e implementa auth" | ESCALATE | Architecture decision + implementation = ADR-008 pipeline. Suggest TL + sprint flow. |
 
+### 9.4 Frontend design gate (impeccable) — §6.6
+
+| Prompt | Flow |
+|---|---|
+| "cria a tela de login em Angular" | ROUTE → `frontend-developer`. Then §6.6: ask "usar impeccable?" → Sim → (install se ausente) `npx skills add pbakaus/impeccable` → `/impeccable teach` → `/impeccable polish` → PM resume. |
+| "faz a landing page do produto" | ROUTE → `ux-designer`/`frontend-developer`. §6.6 offer mandatory → on Sim → teach → `/impeccable shape` + `polish`. |
+| "CRUD products: backend + tela Angular + schema" | ORCHESTRATE (3 specialists). The `frontend` subtask triggers §6.6: after the front subtask, offer impeccable → on Sim → teach → `audit`/`polish` the screen → PM aggregates. |
+| "cria endpoint POST /api/v1/products" | No frontend/ux domain → §6.6 does NOT fire. |
+
 ---
 
 ## 10. Hand-off

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