@eltonssouza/development-utility-kit 1.0.0

package/CLAUDE.md

@@ -0,0 +1,453 @@
+## Project Identity
+
+> **Modifique apenas esta seção ao adotar o plugin em um novo projeto.**
+> Todas as demais seções são base do plugin e não devem ser alteradas diretamente
+> — use `update-template` para receber atualizações.
+
+- **Project name**: `<project-name>`
+- **Project type**: `backend` | `frontend` | `fullstack` | `mobile` | `library` | `cli` | `data-pipeline`
+- **Primary stack**: `<lang> <version> + <framework> <version>` (ex: `Java 21 + Spring Boot 3.2`, `Java 25 + Spring Boot 4.0`, `TypeScript + Angular 21`, `Python 3.12 + Django 5`, `Go 1.23 + Gin 1.10`, `React Native 0.84 + Expo SDK 54`)
+- **Database**: `<engine + version>` (ex: `PostgreSQL 17 + Redis 7`, `MongoDB 7`, `nenhum`)
+- **Domain**: `<ex: e-commerce, fintech, healthcare>`
+- **Team size**: `<ex: 3 fullstack>`
+- **Additional rules**: _(deixe vazio se não houver — use para declarar desvios temporários do harness target)_
+
+
+<!-- PLUGIN BASE — não editar abaixo. Use update-template para receber atualizações. -->
+
+# Stack Architect Agent — Project Context
+
+Always respond in **Brazilian Portuguese**. (Assistant chat only — agents/skills/commands content is in English.)
+
+Style: **caveman** on by default — ULTRA for code, FULL for `.md`, LITE for contract/PRD. See [`.claude/skills/caveman/SKILL.md`](.claude/skills/caveman/SKILL.md). To turn off: `stop caveman`.
+
+---
+
+## Claude Model
+
+- Default (main session): `claude-opus-4-7` (Opus 4.7). Agentic work + architectural decisions.
+- **Commits**: NUNCA mencionar Claude/Anthropic/AI/LLM/assistant em subject, body ou trailers. Sem `Co-Authored-By: Claude`. Commits devem parecer escritos 100% pelo dev humano. Ver seção `Commit — Restrições obrigatórias`.
+
+### Sub-agents — model per agent (master rule)
+
+Opus is expensive. Use only where the decision is irreversible, macro trade-off, or technical veto. Sonnet = default. Haiku = mechanical.
+
+| Model | When to use | Agents |
+|---|---|---|
+| **Opus 4.7** | Top technical authority on irreversible cross-cutting decisions | `tech-lead` |
+| **Sonnet 4.6** | Product decision, implementation, orchestration, technical decomposition, review, test, UI, history recording | `product-owner`, `analyst`, `backend-developer`, `frontend-developer`, `mobile-developer`, `n8n-specialist`, `ux-designer`, `database-engineer`, `devops-engineer`, `qa-engineer`, `code-reviewer`, `security-engineer`, `gate-keeper`, `sprint-runner`, `brain-keeper`, `release-engineer`, `migrator` |
+| **Haiku 4.5** | Scaffold, template sync, stack resolution (mechanical) | `scaffold`, `update-template`, `stack-resolver` |
+
+**Non-negotiable**: never promote an agent to Opus without justification "irreversible decision or macro trade-off". Routine implementation always Sonnet.
+
+---
+
+## Stack Architecture (per ADR-026 / ADR-027 / ADR-029)
+
+The harness is **stack-agnostic by default**. Stack-specific rules (Java vs Python vs Go, Spring Boot 3 vs 4, Angular 18 vs 21) live in **knowledge packs** at `.claude/stacks/<lang>/<framework>-<major>.md`, NOT hardcoded in agents or this CLAUDE.md.
+
+### How it works
+
+1. **Project declares stack** in `## Project Identity` above.
+2. **`stack-resolver` agent** reads Project Identity, locates matching pack, returns rendered STACK CONTEXT block.
+3. **Skills (`run-sprint`, `auto-test-guard`, `quick-feature`, `pair-debug`)** invoke `stack-resolver` at Step 0, inject STACK CONTEXT into downstream agent prompts (pre-resolution — Layer 1 of ADR-026 defense).
+4. **Specialist agents** (`backend-developer`, `frontend-developer`, etc.) consume STACK CONTEXT from the prompt and apply stack-specific patterns from the pack (Layer 2).
+5. **Agents emit `[STACK: <lang>/<framework>-<major> | PACK: loaded|none]`** as first output line for post-hoc validation (Layer 3).
+
+### Pack lifecycle
+
+- `active` (in use) → `deprecated` (no project references it) → `archived` (preserved for history).
+- Up to 3 active packs per language allowed (legacy / current / next).
+- New major = new pack file (do NOT update in-place).
+- Annual security review per active pack (1h/pack/year per ADR-027).
+
+### Project Identity → pack resolution
+
+- `Primary stack: Java 21 + Spring Boot 3.2` → `.claude/stacks/java/spring-boot-3.md`
+- `Primary stack: Java 25 + Spring Boot 4.0` → `.claude/stacks/java/spring-boot-4.md`
+- `Primary stack: TypeScript + Angular 21` → `.claude/stacks/typescript/angular-21.md`
+- `Primary stack: Python 3.12 + Django 5` → `.claude/stacks/python/django-5.md` (create via `create-stack-pack` if missing)
+
+### Pack missing? → skill `create-stack-pack`
+
+When `stack-resolver` finds no pack for declared stack, dispatches `create-stack-pack` skill — conversational generator (8 questions) using `.claude/stacks/_template.md` as base. PRs back to harness repo for reuse across projects.
+
+### Active stack packs (this harness — index)
+
+See `.claude/stacks/README.md` for the up-to-date index. Current active packs:
+- `java/spring-boot-3` (legacy maintenance — Java 17/21 + SB 3.2+)
+- `java/spring-boot-4` (greenfield default — Java 25 + SB 4.0+)
+- `typescript/angular-18`, `angular-19`, `angular-21`
+
+### Local overrides (`.claude/local/`)
+
+Per ADR-032: customizations specific to one project go in `.claude/local/stacks/`, `.claude/local/agents/`, `.claude/local/skills/`. Loader priority: `local/` wins over harness. Never touched by `duk install`.
+
+---
+
+## Skills (Cowork + Claude Code)
+
+Skills in `.claude/skills/` trigger automatically by keyword. **Single entry layer** — commands deleted 2026-05-25. Default entry point for every prompt.
+
+| Skill | When it triggers | Output |
+|---|---|---|
+| `caveman` | Always on; "caveman lite/full/ultra", "stop caveman" | Telegraphic output (~65–75% fewer tokens) |
+| `project-manager` | **Catch-all fallback**: any task without a more specific skill — "create endpoint", "review code", "dockerize", "audit security", "design DB", "create mobile app", "n8n workflow", "wireframe", "migrate", "release prep", "architecture decision", "break into requirements" | Routes to ONE specialist agent (analyst, architect, backend-developer, frontend-developer, code-reviewer, database-engineer, devops-engineer, mobile-developer, n8n-specialist, product-owner, qa-engineer, security-engineer, tech-lead, ux-designer, migrator, release-engineer, auditor) via Task tool |
+| `scaffold` | "scaffold the project", "scaffold backend", "scaffold frontend", "bootstrap fullstack", "monta o esqueleto", "scaffolda o projeto" | Reads `type:` from `## Project Identity`; dispatches to `scaffold` agent for backend/frontend/fullstack pipeline |
+| `run-sprint` | "run sprint X", "execute the sprint" | Sprint implemented with green tests via `sprint-runner` agent |
+| `api-integration-test` | "test integration", "smoke" | Real report (curl + Chrome MCP) |
+| `auto-test-guard` | End of task; "run tests", "generate tests", "full suite" | Generates tests + full regression via `gate-keeper` agent. Blocks if it breaks. |
+| `prd-ready-check` | "PRD-ready?", "DoD" | GO / NO-GO |
+| `test-coverage-auditor` | "audit coverage", "debt map" | Debt report + P0/P1 notes. Gate in `prd-ready-check`. |
+| `pair-debug` | "pair debug", "investigate this bug", "find root cause" | Hypothesis-driven debug loop (no "try and see") |
+| `grill-me` | "grill me", "me entrevista sobre", "stress-test o plano" (opt-in) | Discovery interview → `DISCOVERY_*.md` + handoff to `analyst` (ADR-011 + ADR-013) |
+| `brain-keeper` | End PLAN_*; "record in brain", "update brain" | Provisions `docs/brain/` + `.obsidian/` with color snippet; daily/feature/ADR/bug/tech-debt/migrations + MOC |
+| `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` |
+| `honcho-memory` | "lembra que", "remember that", "memoriza", "/honcho save", "/honcho search", "/honcho list", "/honcho forget", "/honcho status", "/honcho setup" | Persistent cross-session memory via Honcho v3 self-hosted (per-dev instance). Memorizes **user habits + project context**, not technical rules (those live in packs — see ADR-031) |
+
+See [`.claude/skills/README.md`](.claude/skills/README.md) and [`.claude/stacks/README.md`](.claude/stacks/README.md).
+
+**Architecture rule**: 2 layers — Skill (entry point) + Agent (executor). No commands. Specific skills win by keyword match; everything else falls into `project-manager`.
+
+---
+
+## Sub-Agent Routing
+
+| Task | Agent | When to use |
+|---|---|---|
+| **Product/business** | **`product-owner`** | Top authority. Scope, rule, priority, flow, UX, MVP, persona, metric, API contract. Decides. Escalates only in 4 irreversible situations. |
+| Technical decomposition + PLAN_*.md | `analyst` | PO decision → technical plan with goal-ready DoD. Human path requires discovery artifact from `grill-me` (per ADR-013 + ADR-017). Autonomous callers (`sprint-runner`, `release-engineer`, `quick-feature`) exempt via `caller:` signal in Task prompt. |
+| Stack resolution (mechanical) | `stack-resolver` | Reads Project Identity, locates pack, returns STACK CONTEXT block. Invoked by orchestrating skills at Step 0 (per ADR-026). |
+| **Technical + coordination + architecture** | **`tech-lead`** | Top technical authority. Stack, pattern, refactor, debt, lib, integration, macro architecture, ADR, final review. Decides. Escalates only in 3 situations. |
+| UI/UX + wireframes | `ux-designer` | Screens, flows, a11y, design system (UI lib from STACK CONTEXT) |
+| Backend implementation | `backend-developer` | Endpoint, service, DTO, repository (patterns from STACK CONTEXT pack) |
+| Frontend implementation | `frontend-developer` | Component, service, route, state (framework specifics from pack) |
+| Mobile | `mobile-developer` | iOS/Android, native modules, push, biometric, store deploy (RN/Flutter/native via pack) |
+| Database | `database-engineer` | Schema, index, query, migration, perf (engine specifics from pack) |
+| Infra + deploy | `devops-engineer` | Docker, K8s, CI/CD, cloud (build commands from pack) |
+| Code review | `code-reviewer` | PR initial review (rules from pack) |
+| Security + LGPD | `security-engineer` | OWASP, LGPD audit (impl from pack `## Security` — mandatory per ADR-027) |
+| Tests (write) | `qa-engineer` | Unit, integration, E2E (framework specifics from pack + `quality-standards` skill) |
+| Tests (gate) | `gate-keeper` | Run senior+ gate, validate thresholds, block merge |
+| n8n | `n8n-specialist` | Workflow, integration, AI agent, webhook, deploy |
+| Sprint execution | `sprint-runner` | Executes Sprint N of PLAN, delegates in parallel (Stage 0 stack-resolver) |
+| Scaffold (new project) | `scaffold` | Reads Project type + stack, runs appropriate pipeline |
+| Release flow | `release-engineer` | Version bump, CHANGELOG, tag, commands for human |
+| Stack migration | `migrator` | Consumes 2 packs (FROM + TO), multi-major incremental, fullstack sequential (per ADR-030) |
+| History recording (Obsidian vault) | `brain-keeper` | End of PLAN_*: daily, feature, ADR, bug, tech-debt, migration in `docs/brain/` |
+
+### Delegation rules
+
+- **Parallel**: independent tasks without shared files.
+- **Sequential**: output feeds the next (API → consuming component).
+- **Don't delegate**: trivial.
+
+---
+
+## Autonomy Matrix (MASTER RULE)
+
+**Non-negotiable**: agents decide on their own. Asking the human = rare exception. No "I wonder if the user wants X or Y" — the responsible agent **decides and proceeds**.
+
+### Who decides what
+
+| Domain | Agent | Behavior |
+|---|---|---|
+| Product, scope, rule, UX, flow, priority, MVP, persona, API contract | `product-owner` | **Decides alone.** |
+| Stack, pattern, refactor, lib, tool, debt, macro architecture, integration, final review | `tech-lead` | **Decides alone.** Approves/blocks merges. |
+| DB schema, index, migration, perf | `database-engineer` → `tech-lead` (if cross-cutting) | DB engineer decides; TL approves if it affects >1 context. |
+| Security, vuln, OWASP, LGPD | `security-engineer` | **Technical veto** on high/critical — blocks merge without human. |
+| Infra, cost, deploy, CI/CD | `devops-engineer` → `tech-lead` (if >R$200/month) | DevOps decides, except for relevant cost. |
+| UI, microinteraction, tokens, a11y | `ux-designer` → `product-owner` (flow/scope) | UX decides "how visual", PO decides "what". |
+| Implementation | `backend-developer` / `frontend-developer` / `mobile-developer` | Implement what TL defined. Product question → PO. Technical question → TL. **Don't escalate to human.** |
+| Tests, coverage, gate | `gate-keeper` | Blocks if senior+ gate fails. Returns to developer. |
+| Triage between agents | `tech-lead` | Conflict between developers → TL. Conflict TL × PO → joint negotiation. |
+
+### When to escalate to the human (and ONLY when)
+
+**PO escalates ONLY in:**
+1. Irreversible action on real customer data (delete/overwrite without recovery).
+2. Relevant financial cost (paid SaaS, tier change).
+3. Breaking change on PUBLIC contract already published (external client).
+4. Identity/brand change approved by another area.
+
+**TL escalates ONLY in:**
+1. Technical requirement conflict that cannot be resolved with grounding.
+2. Breaking change on public production contract (window with external client).
+3. Infra cost > R$ 200/month additional.
+
+**Specialists NEVER escalate to the human** — they go up to PO (product) or TL (technical).
+
+### Form of escalation (when justified)
+
+Never an open question. Always **proposal + recommendation + impact of the opposite decision**:
+
+> "Provision managed Redis Cluster (+R$ 380/month) to support 10x traffic in 6 months. I recommend approving now; if we keep single-node, cache queue in 2 months."
+
+---
+
+## Senior+ Quality Gate (NON-NEGOTIABLE)
+
+A task = complete only after `auto-test-guard` GREEN on **all** items. No exception. `tech-lead` blocks the merge if anything fails.
+
+These thresholds are **universal across stacks**. Stack-specific tooling (JaCoCo vs coverage.py vs go cover, JUnit vs pytest vs go test) comes from the pack `## Testing` and `## Build & run commands` sections.
+
+| Metric | Threshold | Tool category |
+|---|---|---|
+| Backend coverage (lines) | >= **85%** | Coverage tool from pack (JaCoCo / coverage.py / go cover / ...) |
+| Backend coverage (branches) | >= **80%** | Same |
+| **Backend mutation score** | >= **70%** in domain + application layers | Mutation tool from pack (PIT / mutmut / go-mutesting / ...) |
+| Frontend coverage (statements) | >= **85%** | Jest --coverage / Vitest --coverage |
+| Frontend coverage (branches) | >= **80%** | Same |
+| Static analysis | 0 CRITICAL, 0 HIGH | Stack-specific (SpotBugs / mypy / golangci-lint / ESLint strict / ...) |
+| SonarLint/SonarQube (if configured) | 0 CRITICAL, 0 HIGH, 0 unreviewed hotspot | Sonar |
+| Dependency vuln scan | 0 CVE with CVSS >= 7.0 | Stack-specific (OWASP DC / npm audit / safety / govulncheck / ...) |
+| ESLint frontend | 0 errors, 0 warnings on new code | `eslint --max-warnings 0` |
+| Playwright E2E | 100% green, critical flows covered | Playwright |
+| Browser console in E2E | 0 errors | Chrome MCP |
+| **A11y violations (component)** | 0 `serious` / 0 `critical` | jest-axe |
+| **A11y violations (E2E)** | 0 `serious` / 0 `critical` | @axe-core/playwright |
+| **Performance score (Lighthouse)** | >= **0.80** (median of 3 runs) | @lhci/cli |
+| **LCP (Largest Contentful Paint)** | <= **2500ms** | @lhci/cli |
+| **CLS (Cumulative Layout Shift)** | <= **0.1** | @lhci/cli |
+| **TBT (Total Blocking Time)** | <= **300ms** | @lhci/cli |
+| **Testing pyramid ratio (E2E)** | <= **30%** of total tests (hard-fail above; ideal <= 15%) | `auto-test-guard` count |
+
+**Senior+ gate references ADR-007 for a11y + Lighthouse + pyramid thresholds.**
+
+**Standard senior+ flow (per ADR-008)**:
+1. `product-owner` decides requirements.
+2. `analyst` produces PLAN_*.md with goal-ready DoD.
+3. `tech-lead` proposes ADR when there is a macro decision; approves.
+4. `sprint-runner` executes Sprint N with Stage 0 stack-resolver, delegating in parallel; `qa-engineer` writes tests.
+5. `gate-keeper` generates missing tests + runs the full senior+ gate (coverage, mutation, a11y, Lighthouse, pyramid).
+6. `code-reviewer` initial review (consulting pack § Anti-patterns).
+7. `tech-lead` final review → approves merge OR returns.
+
+**Human never interrupted** — except in the 4 of the PO or 3 of the TL.
+
+---
+
+## Universal Code Conventions
+
+**Stack-specific conventions live in the pack** (`.claude/stacks/<lang>/<framework>-<major>.md` § Code patterns + § Anti-patterns). The conventions below apply **regardless of stack**.
+
+- **DTOs separated from domain entities**. Never expose ORM entities directly through API contracts.
+- **Validation before domain logic**. Use the validation library from the pack.
+- **Error handling explicit**. Never swallow exceptions silently. Map to domain exceptions; map to API error response from the pack.
+- **No `// TODO` / `// FIXME` in committed code**. Track in `docs/brain/architecture/tech-debt.md` with owner + deadline.
+- **Tests are non-negotiable**. Unit + integration + E2E per stack tooling (from pack). Mutation testing on critical layers.
+- **Real engines in integration tests**. Never SQLite / H2 / in-memory as production DB stand-in. Use Testcontainers / equivalent.
+- **APIs versioned** (`/api/v1/...`). Pagination via metadata wrapper.
+- **Logs structured** (JSON), correlation ID propagated. **Never log token, password, PII**.
+- **External calls** have explicit timeout + retry policy + circuit breaker.
+- **Idempotency** on mutating actions when relevant (`Idempotency-Key` header, dedup window).
+- **Secrets** never in committed files. Use env vars / vault.
+
+## Universal SOLID + Clean Code
+
+- **Clean Code + SOLID** applied through code, without naming names ostentatiously.
+- **No premature abstraction**. Interface for one implementation = code smell.
+- **Never suggest a technology without justification**. Simplest solution = best.
+
+## Backend layout (DDD, universal pattern)
+
+The package/folder names below are **conceptual** — actual naming may vary by language (`com.company.project/domain/...` in Java, `app/domain/...` in Python, `internal/domain/...` in Go):
+
+```
+<project>
+├── domain          (entities, value objects, repository ports, domain services)
+├── application     (use cases, DTOs, mappers, orchestration)
+├── infrastructure  (DB adapters, external clients, security, config)
+└── web (or api)    (controllers/handlers, filters, error middleware)
+```
+
+## Frontend layout (universal pattern)
+
+```
+src/
+├── core (or shared infra)  (auth, HTTP client, interceptors, guards)
+├── shared                  (reusable components, pipes/utilities)
+├── features                (lazy-loaded feature modules/routes)
+└── routes/router config
+```
+
+---
+
+## Git Conventions
+
+### Git Flow (padrão obrigatório em todos os projetos)
+
+```
+main        ← produção (apenas merges via PR de release/* ou hotfix/*)
+develop     ← integração (merges de feature/* via PR)
+feature/*   ← novas funcionalidades (base: develop, PR → develop)
+release/*   ← preparação de release (base: develop, PR → main + develop)
+hotfix/*    ← correção urgente em prod (base: main, PR → main + develop)
+bugfix/*    ← correção em dev (base: develop, PR → develop)
+```
+
+**Fluxo padrão de feature:**
+1. `git flow feature start <nome>` (cria `feature/<nome>` a partir de `develop`)
+2. Implementar + commits Conventional Commits
+3. `git flow feature finish <nome>` OU PR `feature/<nome>` → `develop`
+4. PR `develop` → `main` via `release/*` quando pronto para prod
+
+**Fluxo de hotfix:**
+1. `git flow hotfix start <nome>` (base: `main`)
+2. Fix + commit
+3. `git flow hotfix finish <nome>` → merge em `main` E `develop`
+
+- **Commits**: Conventional Commits. `feat(scope): ...` | `fix(scope): ...` | `refactor(scope): ...` | `test(scope): ...` | `docs(scope): ...` | `chore(scope): ...`.
+- **PRs**: "What changed", "How to test", checklist.
+
+### Commit — Restrições obrigatórias (NON-NEGOTIABLE)
+
+- **NUNCA** incluir referências a Anthropic, Claude, AI, LLM ou qualquer assistente no texto do commit (subject, body, trailers).
+- **NUNCA** adicionar linha `Co-Authored-By: Claude ...` ou similar.
+- Commits devem parecer escritos 100% pelo desenvolvedor humano da equipe.
+- Violação bloqueia o commit — `tech-lead` recusa o merge.
+
+---
+
+## Universal Security (always apply)
+
+Stack-specific implementation (SecurityFilterChain in Spring, Django middleware, etc.) lives in the pack `## Security` section (mandatory per ADR-027). Universal principles:
+
+- **Authentication**: stateless tokens (JWT preferred) with short expiry + refresh. MFA hooks ready when domain warrants.
+- **Authorization**: RBAC enforced at use case layer. IDOR validation on every "owned resource" access.
+- **Password hashing**: BCrypt-class adaptive function (cost from pack — typically 12 for BCrypt).
+- **CORS**: explicit origins list. NEVER `*` in production.
+- **Headers**: CSP, HSTS, X-Frame-Options DENY, X-Content-Type-Options nosniff, Referrer-Policy strict-origin-when-cross-origin.
+- **Rate limiting** on public endpoints (auth, signup, password reset).
+- **Secrets**: env vars or vault. NEVER in committed files.
+- **OWASP Top 10**: each pack maps to its stack's mitigation in `## Security § 7.6`.
+
+## Universal Observability (every system in production)
+
+- **Logs**: structured JSON, correlation ID propagated via MDC (or equivalent).
+- **Metrics**: Prometheus exposure with p50/p95/p99 + error rate + throughput.
+- **Tracing**: OpenTelemetry with W3C Trace Context.
+- **Health**: `/health` with readiness + liveness separated.
+
+---
+
+## Database (universal principles)
+
+Stack-specific patterns (Postgres GIN indexes, MongoDB aggregation, Redis sorted sets) live in pack. Universal:
+
+- **UUID = PK by default**. Document natural keys explicitly when used.
+- **TIMESTAMPTZ** (or equivalent) for time fields.
+- **NUMERIC / DECIMAL** for money. NEVER `FLOAT`.
+- **Indexes**: every FK on N-side has an index. Created in the same migration as the table.
+- **Migrations**: versioned, reversible when possible. NEVER `DROP TABLE` / `DROP COLUMN` without an ADR.
+- **EXPLAIN before optimization**.
+
+---
+
+## Frontend — UI Components (universal)
+
+Stack-specific UI lib (ng-bootstrap, Angular Material, Tailwind+shadcn, MUI, etc.) comes from pack. Universal:
+
+- **A11y WCAG 2.1 AA minimum** on every interface (per ADR-007).
+- **Mobile-first responsive**.
+- **Design tokens** (CSS variables) for color, spacing, typography. Theme-aware.
+- **Component states explicit**: default, hover, active, disabled, focus-visible, error, loading, empty.
+
+---
+
+## Infrastructure (universal)
+
+Stack-specific build/run commands from pack `## Build & run commands`. Universal:
+
+- **Docker**: multi-stage build, non-root user (UID >= 10000), healthcheck mandatory.
+- **Compose**: complete dev environment (app + DB + cache).
+- **CI/CD**: build → test → security scan → deploy. Steps from pack.
+- **Secrets**: never in code — vault, env var, CI secret.
+
+---
+
+## Credentials — VPS / N8N / API Keys
+
+When you need access to service VPS, N8N VPS, or API Keys, **always read from**:
+
+```
+C:\development\tools\credentials\vps.txt
+```
+
+Never ask the human for credentials if the file exists. Never commit the file's contents. Never log the value read.
+
+---
+
+## Bootstrap of New Project
+
+### Canonical directory
+
+Every project lives in:
+
+```
+C:\development\source\projects\<project-name>\
+```
+
+### Install harness via npx (recommended)
+
+```bash
+# Install to default OS path:
+#   Windows : C:\development\tools\development-utility-kit
+#   Mac/Linux: ~/development/tools/development-utility-kit
+npx @eltonssouza/development-utility-kit install
+
+# With custom path:
+npx @eltonssouza/development-utility-kit install --sub <dir>
+
+# Preview without writing:
+npx @eltonssouza/development-utility-kit install --dry-run
+
+# Check local vs latest harness version:
+npx @eltonssouza/development-utility-kit install --check-only
+```
+
+Requires Node.js >= 18 and `git` in PATH. If target directory exists and is a valid git repo, the command runs `git pull` (idempotent). If directory exists but is not a git repo, installer aborts with exit 1.
+
+### New project from scratch — CLI scaffold + conversational discovery
+
+```bash
+# 1. CLI scaffolding (mechanical, no questions):
+duk new <project-name>
+# → creates folder + git init + injects .claude/ + empty Project Identity
+
+# 2. Open Cowork or Claude Code in the new folder
+
+# 3. First message in chat: "sabatina pra projeto novo"
+# → stack-discovery skill walks you through 8 questions
+# → fills ## Project Identity
+# → if pack missing for chosen stack: dispatches create-stack-pack
+
+# 4. Then: "scaffolda o projeto"
+# → scaffold skill reads Project Identity + pack, runs stack-appropriate setup
+```
+
+### Batch update across multiple projects
+
+```bash
+# Preview which projects would be updated:
+duk sync-all C:\development\source\projects
+
+# Apply with filters:
+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:<0.2 --apply
+
+# Exclude specific projects:
+duk sync-all C:\development\source\projects --exclude prod-critical --apply
+```
+
+### Help
+
+```bash
+duk help              # general help
+duk help <command>    # command-specific
+duk <command> --help  # same
+```