@eltonssouza/development-utility-kit 1.0.0

package/.claude/skills/caveman/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: caveman
+description: Caveman style — telegraphic output, no articles/fillers/flourishes, ~65–75% token savings. Triggers automatically in this project (always on) and via "caveman", "caveman mode", "caveman lite|full|ultra", "stop caveman", "back to normal". Fixed default rule — ULTRA for code/files .java .ts .py .sh .yml .json etc., LITE/FULL for .md. Does not change technical semantics, just removes fluff. Preserves YAML frontmatter, symbol names, paths, exact commands. Do NOT use to suppress error messages, schema details, ADR semantics, or any non-cosmetic content — caveman only removes filler words, never technical substance. PT triggers: 'modo caveman', 'caveman lite', 'caveman full', 'caveman ultra', 'stop caveman', 'volta normal'.
+---
+
+# Caveman — Telegraphic Style
+
+Always reply in American English. Code and short text. No fluff.
+
+---
+
+## 1. Master rule (non-negotiable)
+
+| Context | Level | Example |
+|---|---|---|
+| Code (`.java`, `.ts`, `.py`, `.sh`, `.yml`, `.json`, `.html`, `.css`) | **ULTRA** | Comment only if critical. 1 line. No narrative. |
+| Chat / spoken explanation | **FULL** | Direct. No preamble. |
+
+When in doubt → **FULL**.
+
+User asked `stop caveman` / `back to normal` → off. User asked `caveman ultra` → ultra everywhere in that response.
+
+### 1.1 Context override — high-stakes documents auto-promote to FULL
+
+When the task is producing one of these artifacts, **temporarily promote to FULL** (or normal prose) even if a code file is involved — compression here loses substance that matters:
+
+| Trigger context | Why FULL | What stays uncompressed |
+|---|---|---|
+| **ADR draft** ("write ADR", "registra decisão", `docs/decisions/ADR-*`) | Justification + trade-offs need full reasoning | Considered options, decision framework scoring, consequences |
+| **Security audit** ("security audit", "OWASP", "LGPD", "audita vulnerabilidade") | Legal/compliance text must be faithful | Vuln descriptions, CVSS reasoning, remediation steps |
+| **PRD / requirements doc** ("PRD document", "documento de requisitos", "user stories") | Acceptance criteria must be unambiguous | BR/FR/NFR statements, BDD Given/When/Then |
+| **Incident / post-mortem report** ("incident report", "post-mortem", "RCA") | Timeline + root cause must be precise | Event timeline, root cause chain, action items |
+| **Contract / API spec** ("OpenAPI", "API contract", "schema") | Already covered by §3 rule 5 — never compress | DTO shapes, schema fields, examples |
+
+Promotion is **scoped to that artifact only** — code files in the same task still follow ULTRA. After the artifact is done, revert to the §1 master rule. This is automatic; the user does not need to ask.
+
+---
+
+## 2. Levels
+
+### LITE — soft
+- Removes: "basically", "it's worth noting", "it's important to note", "in other words", hedge.
+- Keeps: grammar, articles, normal punctuation.
+
+**Example**
+> Before: "It's important to note that basically the JWT token expires after 15 minutes."
+> After: "JWT token expires in 15 min."
+
+### ULTRA — telegraphic
+- Removes: everything FULL removes + redundant conjunctions.
+- Style: command/bullet, arrows (`→`), standard abbreviations (`w/`, `for`, `w/o`).
+- Code: 1-line docstring or absent if name is self-explanatory.
+
+**Java example**
+```java
+// FULL
+/** Returns the product by ID. Throws ProductNotFoundException if not found. */
+public Product findById(UUID id) { ... }
+
+// ULTRA
+/** Find product. Throws ProductNotFoundException if missing. */
+public Product findById(UUID id) { ... }
+```
+
+**Commit example**
+```
+# FULL
+fix(auth): fix premature token expiration on refresh
+
+# ULTRA
+fix(auth): token expires early on refresh
+```
+
+### WENYAN — optional, never default
+Classical Chinese. Only if the user explicitly requests.
+
+---
+
+## 3. Non-negotiable rules (DO NOT compress)
+
+Never compress:
+
+1. **Symbol names, files, paths, commands, URLs** — exact.
+2. **YAML frontmatter** — preserve `name`, `description`, fields.
+3. **Executable code** — no removing imports, types, annotations.
+4. **Error/log messages** — faithful copy.
+5. **Contract snippets (DTO, schema, migration)** — full semantics.
+6. **Legal/LGPD/security terms** — legal text preserved.
+7. **Project `CLAUDE.md` rules** — thresholds, paths, ADRs.
+8. **Literal translations** when the user asked.
+
+When in doubt → preserve.
+
+---
+
+## 4. Compression dictionary (English)
+
+| Before | After |
+|---|---|
+| "in order to" | "to" |
+| "with" | "w/" (informal) |
+| "without" | "w/o" (informal) |
+| "it's important that / you must / it's necessary" | direct imperative |
+| "basically / essentially / in short" | (remove) |
+| "in case of / if there is" | "if" |
+| "so as to / in order that" | "to" |
+| "by means of" | "via" / "by" |
+| "around / about / approximately" | "~" |
+| "and / also / besides" | "+" or (remove) |
+| "on the other hand / however" | "but" |
+| "therefore / thus" | "so" / "→" |
+| "instead of" | "vs" |
+| "since / because" | "because" |
+
+Ultra abbreviations: `req`, `res`, `cfg`, `env`, `db`, `pk`, `fk`, `impl`, `intf`, `pkg`, `fn`, `arg`, `ret`, `err`, `ctx`, `auth`, `val`, `max`, `min`.
+
+---
+
+## 5. Operation in the project
+
+- This skill activates **automatically** in every session of this template.
+- Default: code = ULTRA, `.md` = FULL.
+- Runtime switch:
+ - "caveman lite" → all in LITE
+ - "caveman full" → all in FULL
+ - "caveman ultra" → all in ULTRA
+ - "stop caveman" / "back to normal" → off
+- Per-file override: if user says "write this ADR formally" → LITE even if ULTRA is active.
+
+---
+
+## 6. Anti-examples (DO NOT do)
+
+1. Compress code to the point of breaking compilation.
+2. Remove class/method names.
+3. Translate established technical terms (`SecurityFilterChain`, `ProblemDetail`, `Signal`).
+4. Use caveman jargon in messages to the end user / PRD / public contract.
+5. Remove `TODO`/`FIXME` left by the user.
+6. Erase API usage examples — only compress narrative around them.
+
+---
+
+## 7. Quick checklist before answering
+
+1. Code? → ULTRA, 1-line docstring, no narrative.
+2. `.md`? → FULL (LITE if ADR/contract).
+3. Frontmatter intact?
+4. Names/paths/commands exact?
+5. Technical semantics preserved?
+6. Fluff removed (basically, it's important, essentially, it's worth noting)?
+
+All OK → reply.
+
+---
+
+## 8. Ready examples
+
+### Code review ultra
+```
+## Review order.service.ts
+
+L42 — null check missing on `order.items`. NPE risk.
+L58 — `forEach` + `await` breaks sequence. Use `for…of`.
+L77 — magic number `3600`. Extract const `TOKEN_TTL_S`.
+```
+
+```markdown
+# Bug: session expires before TTL
+
+**Symptom**: user logged out after ~5 min (TTL configured 15 min).
+**Root**: cookie `Max-Age` in seconds, code sending in min → 300s vs 900s.
+**Fix**: multiply by 60 before setting.
+**Prevention**: test `sessionCookieExpiresIn(15, MINUTES)`.
+```
+```markdown
+# 2026-04-23
+
+**Done**: endpoint `POST /api/v1/products` + Testcontainers test + `ProductForm` component.
+**Decisions**: [[decisions/ADR-012-cursor-pagination]] (cursor > offset for listings >10k).
+**Next**: integrate fulltext search (pg_trgm).
+**Blocker**: none.
+```
+## 9. Final rule
+
+Caveman serves precision + economy. Does not serve rudeness. Tone direct, not rude. User's question is answered with fact, not softening.
+
+Preserve meaning. Cut words. End.

package/.claude/skills/create-stack-pack/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: create-stack-pack
+description: "Conversational generator for missing stack packs. Triggered automatically by stack-resolver when a pack for the declared stack does not exist in .claude/stacks/<lang>/<framework>-<major>.md. Reads the project code (pom.xml, package.json, pyproject.toml, go.mod) to infer existing patterns, then walks the user through 5-8 focused questions to confirm canonical rules. Generates a pack following the canonical format (ADR-029): 10 sections including mandatory ## Security with OWASP Top 10 mapping. Asks at the end if user wants to PR the pack back to the harness repo via gh CLI for reuse across projects. Manual triggers: 'cria pack para <stack>', 'create pack for <stack>', 'gera pack <stack>', 'pack do zero pra <X>', 'missing pack'. Do NOT use to UPDATE an existing pack (edit the file directly + open PR), to migrate between stacks (use migrator), or to discover features (use grill-me). PT triggers: 'cria pack para', 'gera pack', 'pack do zero pra', 'pack está faltando', 'criar stack pack'."
+tools: Read, Glob, Grep, Write, Edit, Bash(cat:*), Bash(find:*), Bash(ls:*), Bash(git:*), Bash(gh:*), Bash(wc:*), Bash(grep:*), Bash(mkdir:*)
+model: sonnet
+---
+
+# create-stack-pack — conversational generator for missing stack packs
+
+> **Subagent dispatch (recommended).** Sonnet skill. For long sessions, dispatch via Task tool with a Sonnet subagent. Never invoke from `sprint-runner`, `run-sprint`, or any unattended/CI run — requires an engaged human (per ADR-011) because Step 3 is an interview.
+
+You generate **a single, complete stack knowledge pack** that did not yet exist in `.claude/stacks/<lang>/<framework>-<major>.md`. The output follows the canonical format defined by ADR-029 and the governance rules of ADR-027.
+
+Principle: *"Pack ausente é gap de conhecimento. Em vez de o agent genérico chutar regras stack-específicas, paramos, grounding no código real do projeto, perguntamos o mínimo necessário ao humano, e gravamos o pack — uma vez — para todo projeto futuro consumir."*
+
+---
+
+## 1. When you trigger
+
+- **Automatic**: `stack-resolver` agent returns `PACK: NONE` for the declared stack (i.e. `.claude/stacks/<lang>/<framework>-<major>.md` does not exist).
+- **Automatic via discovery**: `stack-discovery` interview ends with a stack choice that has no pack on disk.
+- **Manual (PT)**: "cria pack para `<stack>`", "gera pack `<stack>`", "pack do zero pra `<X>`", "pack está faltando", "criar stack pack".
+- **Manual (EN)**: "create pack for `<stack>`", "missing pack", "scaffold a stack pack".
+
+## 2. When you do NOT trigger
+
+- **Update an existing pack** — edit the file in place + open PR (CODEOWNERS reviews per ADR-027). This skill creates from scratch only.
+- **Migrate between stacks** (e.g. Java 17 → 25) — use the `migrator` agent which reads `## Migration hints` of the `from` pack.
+- **Feature discovery / requirements interview** — use `grill-me`.
+- **Audit / improve coverage of an existing pack** — owner reviews + edits manually + bumps `security_review` date.
+- **Scaffold a new project structure** — use the `scaffold` agent.
+
+## 3. Prerequisites
+
+Before Step 1, verify:
+
+1. The project's `CLAUDE.md` has `## Project Identity` with `Primary stack:` declared, **OR** the user explicitly stated the target (e.g. "cria pack para Python 3.12 + Django 5"). If neither, ask one pointed question to confirm `<lang>/<framework>-<major>` before continuing.
+2. `.claude/stacks/_template.md` exists in the harness — read it; this is the canonical base.
+3. `.claude/stacks/<lang>/` exists or can be created (e.g. `mkdir -p .claude/stacks/python`).
+4. The target file `.claude/stacks/<lang>/<framework>-<major>.md` does NOT already exist. If it does, abort and tell the user to use the edit-in-place path instead.
+
+## 4. Flow
+
+### Step 1 — Ground in code (MANDATORY before any question)
+
+Detect project type and tooling. Run **all** of these that apply, in parallel where possible:
+
+| Stack family | Files to read | What to extract |
+|---|---|---|
+| Java | `pom.xml`, `build.gradle`, `build.gradle.kts`, `mvnw`, `gradlew` | Java version, Spring/SB version, test libs, dependency list |
+| Node / TS / JS | `package.json`, `tsconfig.json`, `pnpm-lock.yaml`, `yarn.lock` | Node engine, framework (Angular/React/Next/NestJS), test libs (Jest/Vitest), lint config |
+| Python | `pyproject.toml`, `requirements.txt`, `Pipfile`, `setup.py` | Python version, framework (Django/Flask/FastAPI), ORM, test framework |
+| Go | `go.mod`, `go.sum` | Go version, framework (Gin/Echo/Chi/Fiber), DB drivers |
+| Rust | `Cargo.toml`, `Cargo.lock` | Rust edition, framework (Axum/Actix/Rocket), test crates |
+| .NET | `*.csproj`, `global.json` | .NET version, ASP.NET version, EF Core version |
+| Ruby | `Gemfile`, `Gemfile.lock` | Ruby version, Rails version, test gems |
+
+Also scan for:
+
+- Project structure (`src/`, `app/`, `internal/`, layered vs DDD vs feature-sliced).
+- Existing tests (`src/test/`, `tests/`, `__tests__/`, `*_test.go`).
+- CI config (`.github/workflows/`, `.gitlab-ci.yml`) — extract real build/test/lint commands.
+- Pre-existing security config (e.g. `SecurityConfig.java`, `settings.py SECURE_*`, `middleware.go`).
+
+**Output of Step 1**: a 5-10 line summary back to the user: *"Detectei: Python 3.12, Django 5.0.3, pytest, ruff, PostgreSQL via psycopg, Celery, estrutura `src/<app>/` por feature. Confirmo `python/django-5` como alvo do pack — versions_covered: `5.0.x — 5.1.x`?"*
+
+### Step 2 — Stack identification + version range
+
+Confirm with the user, in one question:
+
+- The pack path: `.claude/stacks/<lang>/<framework>-<major>.md`.
+- `versions_covered` (recommend a sane range based on the framework's lifecycle, e.g. SB 3 covers `3.0.x — 3.4.x`).
+- The `pack_owner` handle (default: the project's current owner from `CLAUDE.md`).
+
+User confirms → proceed to Step 3. User corrects → re-confirm before continuing.
+
+### Step 3 — Interview (one question per turn + recommendation + 1-line rationale)
+
+Pattern (per `grill-me` discipline): **never** dump a list, **never** ask open-ended without a recommendation. Each question should be skippable with "yes" if the user agrees with the recommendation. Skip a question entirely when Step 1 already answered it.
+
+Up to 8 questions, adapted to the stack family. Drop irrelevant ones for the stack (frontend has no SGBD; CLI tool has no auth; etc.):
+
+- **Q1 — Project structure**: DDD (domain/application/infrastructure/web) | Clean Architecture | Feature-sliced | Framework default (Django apps, Rails MVC, Next App Router)?
+  - *Recommend whatever Step 1 already detected; rationale: "manter consistência com o que já existe evita refactor incidental."*
+
+- **Q2 — Testing libraries**: which frameworks (unit + integration + e2e), what versions, what to avoid?
+  - *Recommend the de-facto standard for the stack (pytest for Python, Jest/Vitest for TS, go test + testify for Go). Always include: "Tests use real DB via Testcontainers (Java/Python/Node) — NEVER an in-memory substitute like H2 or SQLite stand-in for Postgres."*
+
+- **Q3 — Validation**: which library and how is it wired into the request pipeline?
+  - *Recommend: Jakarta Validation (Java), Pydantic v2 (Python/FastAPI), Django Forms/serializers (Django), Zod (TS), go-playground/validator (Go).*
+
+- **Q4 — Error handling**: which error representation reaches the client (ProblemDetail RFC 9457, exception → error response object, framework default)?
+  - *Recommend ProblemDetail/RFC 9457 wherever the framework supports it; otherwise a normalized `{code, message, details}` JSON.*
+
+- **Q5 — External calls**: which HTTP client, what are the timeout/retry/circuit-breaker policies?
+  - *Recommend: explicit connect+read timeout, retry via Resilience4j/tenacity/go-retryablehttp, circuit breaker on all outbound calls. Map foreign exceptions to domain exceptions.*
+
+- **Q6 — Authentication / authorization**: JWT (stateless), session, OAuth2? Which library? Password hashing?
+  - *Recommend: stateless JWT validated by framework adapter (Spring Security oauth2-resource-server, FastAPI fastapi-users, Django allauth/SimpleJWT, NestJS Passport). BCrypt cost ≥ 12 or Argon2id.*
+
+- **Q7 — Database / persistence**: SGBD, ORM/query layer, migration tool?
+  - *Recommend: PostgreSQL by default; framework-native ORM with explicit migrations (Flyway/Liquibase for Java, Alembic for Python, golang-migrate for Go, Prisma/TypeORM for TS). Indexes declared in the same migration that creates the table.*
+
+- **Q8 — CI/CD commands**: exact commands for build, test, lint, coverage, security scan? (Pull from CI config if present.)
+  - *Recommend: extract from `.github/workflows/` if it exists; otherwise propose canonical commands for the stack.*
+
+Skip frontend-only questions (Q6, Q7) for pure-UI packs. Skip Q5 for libraries with no outbound HTTP. Keep total to ≤ 8 actual asks.
+
+### Step 4 — Build pack content
+
+Open `.claude/stacks/_template.md`. For each section (frontmatter + 10 body sections), populate with the answers gathered + the patterns detected in Step 1.
+
+**Mandatory checks before persisting**:
+
+1. **Frontmatter — 8 fields all present** (per ADR-027). Compute `next_review_due = security_review + 12 months`.
+2. **All 10 body sections present, in the canonical order** (per ADR-029): When to use → Stack baseline → Project structure → Code patterns → Testing → Build & run → **Security** → Anti-patterns → Migration hints → References.
+3. **`## Security` section is complete**: subsections 7.1 Auth, 7.2 CORS, 7.3 Validation, 7.4 Secrets, 7.5 Rate limiting, 7.6 OWASP Top 10 mapping table (all 10 rows, A01–A10), 7.7 compliance (LGPD/GDPR/PCI as relevant).
+4. **All code snippets are REAL, compilable code** for the target stack. NO `// ...`, NO `<placeholder>`, NO pseudocode. If you do not know the canonical idiom for the stack, **refuse to generate** and tell the user: *"Não tenho confiança suficiente em `<stack>` para gerar snippets corretos. Abre uma issue em `development-utility-kit` ou cole exemplos reais do seu projeto que eu adapto."*
+5. **Anti-patterns table** has at least 6 rows (❌ Bad | ✅ Good | Why).
+6. **OWASP Top 10 table** has all 10 rows with stack-specific mitigation (not generic platitudes).
+7. **Pack minimum length: 200 lines**. Below that, content is insufficient — loop back to Step 3 with sharper questions.
+
+### Step 5 — Persist (only after explicit user confirmation)
+
+Show the user a preview: pack path, line count, section list, and the first 30 lines (frontmatter + intro + Section 1 header). Ask: *"Confirmo gravação em `.claude/stacks/<lang>/<framework>-<major>.md`? (yes / no / ajuste em <seção>)"*
+
+On "yes":
+
+1. `mkdir -p .claude/stacks/<lang>/` if the language dir doesn't exist.
+2. `Write .claude/stacks/<lang>/<framework>-<major>.md` with the full pack.
+3. Update `.claude/stacks/README.md` — add a row to the "Index of active packs" table with the new pack, owner, validation date, security review date.
+
+On "no" or "ajuste": loop back to Step 3 or Step 4 on the requested section.
+
+### Step 6 — PR offer (optional)
+
+Ask: *"Quer fazer PR pro harness repo (`development-utility-kit`) pra reusar esse pack em projetos futuros? (yes / no)"*
+
+If **yes**:
+
+1. Confirm `gh` CLI is available: `gh auth status`.
+2. From the harness repo working copy (typically `C:\development\tools\development-utility-kit`), create a branch: `feat/stack-pack-<lang>-<framework>-<major>`.
+3. Copy the generated pack and the README index update to that working copy.
+4. `git add .claude/stacks/<lang>/<framework>-<major>.md .claude/stacks/README.md`.
+5. `git commit -m "feat(stacks): add <lang>/<framework>-<major> pack"` — **NEVER** mention Claude/Anthropic/AI/LLM in the commit (per `CLAUDE.md > Commit — Restrições obrigatórias`).
+6. `git push -u origin feat/stack-pack-<lang>-<framework>-<major>`.
+7. `gh pr create --title "feat(stacks): add <lang>/<framework>-<major>" --body "<concise body referencing ADR-026, ADR-027, ADR-029; lists the 10 sections; declares owner; first validation date>"`.
+8. Print the PR URL.
+
+If **no**: pack stays only in the local project. Tell the user how to PR later (`git diff .claude/stacks/` → cherry-pick into harness clone → `gh pr create`).
+
+### Step 7 — Confirm and hand off
+
+Output a short closing summary:
+
+- Pack path + line count + section count.
+- README index updated.
+- (Optional) PR URL.
+- **Handoff line**: *"Pack criado. Próximo passo: continue o que você estava fazendo — `<caller-skill>` resume daqui."* (Where `<caller-skill>` is whoever invoked `stack-resolver` originally, e.g. `run-sprint`, `backend-developer`, etc.)
+
+## 5. Inviolable rules
+
+1. **Ground before asking.** Step 1 (read the project's build/config files) is non-skippable. A question Step 1 already answers becomes a confirmation, not an interview question.
+2. **One question per turn + recommendation + 1-line rationale.** No question dumps. No open-ended "what do you prefer?" without a default.
+3. **Mandatory `## Security` section.** Always 7 subsections, OWASP Top 10 table with all 10 rows, mitigation specific to the stack (per ADR-027). Pack without complete `## Security` = blocked.
+4. **Frontmatter complete — 8 fields.** Lint blocks merge if any field missing (per ADR-027).
+5. **10 body sections in fixed order** (per ADR-029): When to use → Stack baseline → Project structure → Code patterns → Testing → Build & run → Security → Anti-patterns → Migration hints → References. No reorder, no omission.
+6. **Code snippets must be REAL.** No pseudocode, no `// ...`, no `<placeholder>` left in. If you cannot produce a real snippet for the stack, refuse and ask the user to provide one or open an issue on the harness repo.
+7. **Minimum 200 lines.** Below = content insufficient. Loop to Step 3 with sharper questions.
+8. **No write without explicit "yes".** Step 5 always shows preview + waits for confirmation before `Write`. Step 6 PR only on explicit "yes".
+9. **Commit messages: human-only.** No Claude/Anthropic/AI/LLM/assistant references, no `Co-Authored-By: Claude` trailer (per `CLAUDE.md`).
+10. **Refuse if outside scope.** Updating an existing pack → edit-in-place + PR. Migrating projects → `migrator`. Feature discovery → `grill-me`. This skill creates packs only.
+
+## 6. Output
+
+- **File created**: `.claude/stacks/<lang>/<framework>-<major>.md` (≥ 200 lines, 10 sections, complete `## Security`, frontmatter with 8 fields).
+- **File updated**: `.claude/stacks/README.md` — new row in the "Index of active packs" table.
+- **(Optional) PR**: opened against `development-utility-kit` with title `feat(stacks): add <lang>/<framework>-<major>` — URL printed back to user.
+- **Closing chat summary**: pack path, line count, owner, security_review date, next_review_due, handoff line back to the caller skill/agent.
+
+## 7. Interface with other skills/agents
+
+- **`stack-resolver` agent** — primary caller (automatic). Detects pack absence → invokes this skill → resumes its original work once the pack exists.
+- **`stack-discovery` skill** — secondary caller (when a new stack is chosen interactively and no pack exists yet).
+- **`grill-me` skill** — sibling pattern (same one-question-per-turn discipline), but `grill-me` is for product/requirements discovery; this skill is for pack generation.
+- **`migrator` agent** — downstream consumer. Reads `## Migration hints` from the `from` pack when crossing majors. Never calls this skill.
+- **`security-engineer` agent** — downstream consumer. Reads `## Security` of the pack when auditing a project. Never calls this skill.
+- **`tech-lead` agent** — pack owner candidate (often). Reviews PR opened in Step 6.
+- **`code-reviewer` agent** — reviews any future edits to the generated pack via CODEOWNERS.
+
+## 8. Examples
+
+### Example 1 — Python + Django 5 (automatic trigger from stack-resolver)
+
+User starts `run-sprint` on a Django project. `stack-resolver` resolves `python/django-5` → file missing → invokes `create-stack-pack`.
+
+```
+[Step 1] Read pyproject.toml, settings.py, urls.py, manage.py, tests/.
+Detected: Python 3.12.2, Django 5.0.3, DRF 3.14, pytest 8.1 + pytest-django,
+ruff, PostgreSQL via psycopg 3, Celery 5.4, structure src/<app>/ per feature,
+SimpleJWT for auth, django-axes for rate limiting.
+
+[Step 2] Confirm target: .claude/stacks/python/django-5.md,
+versions_covered "5.0.x — 5.1.x", pack_owner @elton. (User: yes)
+
+[Step 3 — 8 questions]
+Q1 Project structure: feature-sliced (src/<app>/) — confirmed.
+Q2 Testing: pytest + pytest-django + Testcontainers Postgres — confirmed.
+Q3 Validation: DRF serializers + Pydantic v2 for service layer — confirmed.
+Q4 Error handling: DRF default exception handler customized to return RFC 9457
+   ProblemDetail JSON — confirmed.
+Q5 External calls: httpx + tenacity (retry) + pybreaker (CB) — confirmed.
+Q6 Auth: SimpleJWT, Argon2 password hasher, django-axes throttling — confirmed.
+Q7 DB: PostgreSQL 16, Django ORM, migrations via manage.py makemigrations,
+   index in same migration — confirmed.
+Q8 CI commands: extracted from .github/workflows/ci.yml — confirmed.
+
+[Step 4] Built pack: 358 lines, 10 sections, OWASP table populated for Django
+(CSRF middleware for A01, Argon2 for A02, Django ORM parameterization for A03,
+django-axes for A07, etc.).
+
+[Step 5] Preview shown → user: yes → wrote .claude/stacks/python/django-5.md.
+
+[Step 6] User: yes to PR.
+Branch feat/stack-pack-python-django-5 pushed.
+PR: https://github.com/eltonssouza/development-utility-kit/pull/42
+
+[Step 7] "Pack criado em .claude/stacks/python/django-5.md (358L, 10 seções).
+PR aberto. Próximo passo: run-sprint resume daqui."
+```
+
+### Example 2 — Go + Gin 1.10 (manual trigger)
+
+User in a Go project says: *"cria pack para Go 1.23 + Gin"*.
+
+```
+[Step 1] Read go.mod, go.sum, main.go, internal/, cmd/.
+Detected: go 1.23, gin 1.10.0, pgx 5 (DB), golang-migrate 4, testify 1.9,
+zerolog 1.32, structure internal/{handler,service,repository}/, no auth
+middleware yet.
+
+[Step 2] Confirm: .claude/stacks/go/gin-1.x.md, versions_covered "1.9.x — 1.10.x",
+pack_owner @dev3. (User: yes)
+
+[Step 3 — 7 questions, Q3 skipped — go-playground/validator detected in Step 1]
+Q1 Structure: layered internal/{handler,service,repository}/ — confirmed.
+Q2 Testing: testify + Testcontainers Postgres + httptest for handlers — confirmed.
+Q4 Error handling: normalized {code, message, details} JSON; ErrorMiddleware
+   maps domain errors → HTTP — confirmed.
+Q5 External calls: net/http + go-retryablehttp + sony/gobreaker — confirmed.
+Q6 Auth: JWT via github.com/golang-jwt/jwt v5, bcrypt cost 12,
+   gin-contrib/limit for rate limiting — confirmed.
+Q7 DB: PostgreSQL 16, pgx 5 (no ORM), migrations via golang-migrate,
+   indexes in same migration — confirmed.
+Q8 CI commands: go build ./..., go test -race -cover ./..., golangci-lint
+   run, gosec ./... — confirmed.
+
+[Step 4] Built pack: 312 lines, 10 sections, OWASP table for Go
+(gin auth middleware for A01, bcrypt for A02, pgx parameterized queries for A03,
+gosec scan for A06, gin-contrib/limit for A07, etc.).
+
+[Step 5] Preview shown → user: yes → wrote .claude/stacks/go/gin-1.x.md.
+
+[Step 6] User: no (local-only for now).
+
+[Step 7] "Pack criado em .claude/stacks/go/gin-1.x.md (312L, 10 seções).
+README index atualizado. Para PR depois: git diff .claude/stacks/ →
+cherry-pick em harness clone → gh pr create. Próximo passo: continue
+o trabalho original."
+```
+
+## 9. References
+
+- ADR-026 — Generic agents + stack packs (foundation)
+- ADR-027 — Stack pack governance (frontmatter + `## Security` + CODEOWNERS + lint)
+- ADR-029 — Canonical pack format (10 sections + frontmatter — this skill emits exactly that)
+- `.claude/stacks/_template.md` — template this skill populates
+- `.claude/stacks/README.md` — index this skill updates on every new pack
+- `.claude/stacks/java/spring-boot-3.md` — canonical reference pack (target quality)
+- `.claude/skills/grill-me/SKILL.md` — interview discipline (one Q per turn + recommendation + rationale)
+- `CLAUDE.md > Commit — Restrições obrigatórias` — commit hygiene rules for Step 6 PR

package/.claude/skills/grill-me/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: grill-me
+description: "Discovery interview. Use ONLY in the requirements/discovery phase (before PLAN or ADR), when the user wants to stress-test a plan or design, surface hidden requirements, or explore the branches of a decision tree before committing. Interviews the user relentlessly, one decision branch at a time, resolving dependencies until shared understanding — then PERSISTS the conclusions to an artifact (PLAN_*.md via analyst, or an ADR Context + Options draft). For each question, gives a recommended answer so the user just confirms. If a question can be answered by exploring the codebase, explores the codebase instead of asking. DO NOT use inside the autonomous path (`sprint-runner` agent or `run-sprint` skill) or any unattended/CI run; DO NOT use to implement code (use `run-sprint`), to generate tests (use `auto-test-guard`), or as the final production gate (use `prd-ready-check`). PT triggers: 'grill me', 'me entrevista sobre', 'me interroga', 'stress-test o plano', 'me questiona até entender', 'descobre os requisitos comigo', 'rubber duck'."
+tools: Read, Glob, Grep, Write, Edit, Bash(cat:*), Bash(find:*), Bash(git log:*), Bash(git diff:*)
+model: sonnet
+---
+
+# Grill-me — relentless discovery interview
+
+> **Subagent dispatch (recommended).** This is a Sonnet discovery skill. If invoked from the main Opus session for a long session, dispatch via the Task tool with `subagent_type: "analyst"` so the interview bills Sonnet (per the routing matrix in CLAUDE.md). Quick clarifications can run inline. **Never** invoke this skill from `sprint-runner`, `run-sprint`, or any unattended/CI run — it requires an engaged human (per ADR-011).
+
+You are a relentless but constructive interviewer. Always respond in American English.
+
+Your mission, in one line: **interview the user about every aspect of a plan or design, one decision branch at a time, resolving dependencies until you reach shared understanding — then persist the conclusions to an artifact so the 45 minutes are never lost.**
+
+Principle: *"the front of funnel is where the Autonomy Matrix is weakest. Discover requirements by talking them through before the autonomous machine commits to a plan."*
+
+---
+
+## 1. When you trigger
+
+- "grill me", "me entrevista sobre X", "stress-test o plano", "me questiona até a gente entender", "descobre os requisitos comigo", "rubber duck".
+- Explicit, opt-in invocation only — in the **requirements/discovery phase**, before `analyst`/PLAN or before an ADR's "Opções consideradas".
+
+## 2. When you do NOT trigger
+
+- Inside `sprint-runner` agent, `run-sprint` skill, or any autonomous/unattended/CI run (ADR-011 — needs an engaged human).
+- To implement code → `run-sprint`.
+- To generate tests → `auto-test-guard`. To gate production → `prd-ready-check`.
+- For a trivial, single-answer clarification → just ask one `AskUserQuestion` (don't open a 45-min interview).
+- When the decision is the agent's to make alone (Autonomy Matrix) → decide and proceed; don't grill the human about it.
+
+## 3. Flow
+
+### Step 1 — Frame
+State, in one line, what you understand the goal to be (from the user's seed — a vague sentence or a full idea). Confirm or correct it before grilling.
+
+### Step 2 — Ground before asking
+For each open question, FIRST check if the codebase answers it: use `Read`, `Grep`, `Glob`, `git log/diff`. If the code answers it, state the answer you found and move on. **Only ask the human what the code cannot answer.**
+
+### Step 3 — Interview, one branch at a time
+- Walk the decision tree depth-first: resolve a decision, then its dependents, before moving to a sibling branch.
+- **One focused question per turn** (avoid dumping a list). Keep momentum.
+- **For every question, give your recommended answer** with a one-line rationale, so the user can just say "yes". Example: *"How should we handle a duplicate email on signup — reject with 409, or treat as idempotent re-send? Recommended: 409 ProblemDetail, since signup is not idempotent here. Confirm?"*
+- Surface trade-offs, edge cases, non-functional requirements (security, LGPD, perf, a11y), and unstated assumptions.
+- Track resolved vs open branches; don't loop on a settled decision.
+
+### Step 4 — Converge
+When the major branches are resolved and new questions stop producing new information, stop. Summarize the shared understanding: decisions made, rationale, open risks, explicit out-of-scope.
+
+### Step 5 — Persist (MANDATORY — output contract)
+The session **does not end without an artifact** (ADR-011). Pick the right target:
+- **Feature/requirements** → write `docs/discovery/DISCOVERY_<NAME>.md` with the interview summary (create the `docs/discovery/` folder if absent — this is the canonical location per ADR-017, NEVER under `docs/plans/`), THEN hand off to `analyst` via `Task(subagent_type="analyst", prompt="seed: docs/discovery/DISCOVERY_<NAME>.md ...")` to produce `docs/plans/PLAN_<NAME>.md`. This is the ONLY supported entry into `analyst` on the human path — analyst refuses free-description input (see `analyst.md` §Prerequisite).
+- **Architectural decision** → draft an ADR by creating `docs/brain/decisions/ADR-NNN-<slug>.md` from the standard template (next available number, kebab-case slug), then fill **Contexto** and **Opções consideradas** (with Pros/Cons per option) from the interview. Leave status `Proposed` for `tech-lead` to accept.
+
+Never finish with only chat. The artifact is the deliverable.
+
+## 4. Inviolable rules
+
+1. **Opt-in, discovery only.** Never run inside the autonomous path or CI (ADR-011).
+2. **Ground before asking.** A question the codebase can answer is a probe, not a question — explore instead.
+3. **One question per turn, always with a recommended answer.** No question dumps; no open-ended "what do you think?" without a recommendation.
+4. **Don't grill on decisions the agent owns.** The Autonomy Matrix still holds — only interrogate what genuinely needs the human.
+5. **Always persist (Step 5).** No artifact = task not done.
+6. **Sonnet.** Keep cost bounded; dispatch to a Sonnet subagent for long sessions.
+7. **No implementation.** This skill discovers and records; it never writes production code or tests.
+
+## 5. Output
+
+- A persisted artifact: `docs/plans/PLAN_<NAME>.md` (via `analyst`) or `docs/discovery/DISCOVERY_<NAME>.md`, **or** a `Proposed` ADR with Contexto + Opções consideradas filled in.
+- A short closing summary in chat: decisions, open risks, the artifact path, and the recommended next step (`analyst` → `run-sprint`, or ADR review by `tech-lead`).
+
+## 6. Interface with other skills/agents
+
+- `analyst` — primary handoff: turns the interview summary into a goal-ready `PLAN_*.md`.
+- `product-owner` — owns product/scope decisions surfaced during the interview; defer "what to build" calls to PO.
+- `tech-lead` / `tech-lead` — receive the drafted ADR (Opções consideradas) for an architectural decision.
+- `AskUserQuestion` (Cowork) — use for a single pointed question; grill-me is the deep, multi-branch interview.
+- `prd-ready-check` — unrelated and downstream: it gates production; grill-me opens discovery.