@eltonssouza/development-utility-kit 0.12.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/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).
 
 ---
 
@@ -128,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`.
@@ -163,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.
 
 ---
 
@@ -233,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:
@@ -264,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.
 
 ---
 
@@ -323,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/dashboard/public/content/docs/skills-reference.en.md

@@ -47,6 +47,8 @@ This document covers the 18 official skills of the harness, grouped by purpose.
 
 Reference: **ADR-033** — orchestrate mode fills the fast-lane gap acknowledged in ADR-008 §Consequences ("8 etapas para feature pequena é cerimônia").
 
+**Frontend design gate (§6.6, ADR-048)**: whenever the dispatch touches the `frontend`/`ux` domain, `project-manager` **must offer the external `impeccable` design gate** (mandatory offer; the user chooses). On "Sim" it runs, in order: install if absent (`npx skills add pbakaus/impeccable`, terminal, per-project) → `/impeccable teach` (analyze project) → `/impeccable <verb>` (polish/audit/…) → then resumes orchestration. Impeccable is a tool, not the authority; `project-manager` never auto-runs it and never abdicates control. Extends ADR-010's gate-keeper WARN check.
+
 **Delegated agent(s)**: variable, per internal routing table. ROUTE dispatches 1; ORCHESTRATE dispatches 2–5 in parallel.
 
 **Output / artifacts**: ROUTE → single `Task(subagent_type="<agent>", description="...", prompt="...")` call. ORCHESTRATE → inline mini-plan table + multiple `Task` calls in the same content block. Final artifacts (code, ADR, report) come from the chosen specialist(s).

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

@@ -311,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

@@ -348,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eltonssouza/development-utility-kit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "npx installer for the development-utility-kit harness",
   "bin": {
     "duk": "bin/cli.js"