@eltonssouza/development-utility-kit 0.17.0 → 0.18.0

package/.claude/CONTEXT.template.md

@@ -0,0 +1,44 @@
+# CONTEXT — project domain glossary
+
+> Per-repo **ubiquitous-language** glossary (ADR-050). Agents read this before
+> exploring code and use its exact vocabulary in plans, issues, code, and tests.
+> Together with the stack pack it forms the project's working context.
+> Copy this template to the project root as `CONTEXT.md` and fill it in
+> (`stack-discovery` / `create-stack-pack` can seed it for you).
+
+## Domain in one paragraph
+
+<What this project is, who uses it, and the core value — 2–4 sentences in the
+team's own words.>
+
+## Ubiquitous language (the glossary)
+
+Use these terms verbatim — never invent synonyms. One row per concept.
+
+| Term | Means | NOT to be confused with |
+|---|---|---|
+| `<Order>` | <a customer's confirmed purchase, after payment> | `Cart` (pre-payment) |
+| `<...>` | <...> | <...> |
+
+## Bounded contexts (if multi-context)
+
+- `<context-name>` — <responsibility>; owns `<entities>`.
+- (Single-context project: write "single context".)
+
+## Core invariants
+
+Business rules that must always hold (named, so plans/tests reference them).
+
+- `INV-1`: <e.g. an Order always has at least one line item>
+- `INV-2`: <...>
+
+## Naming conventions
+
+- Entities/tables: <e.g. singular PascalCase entities, snake_case tables>
+- Endpoints: <e.g. `/api/v1/<plural-resource>`>
+- Events/statuses: <the allowed status strings, exactly>
+
+## Pointers
+
+- ADRs that touch the domain: `docs/brain/decisions/` (or `docs/adr/`)
+- Stack pack: resolved from `## Project Identity` via `stack-resolver`

package/.claude/agents/analyst.md

@@ -31,17 +31,25 @@ Do NOT generate the PLAN from a free description in the human path.
 
 Receive an ambiguous feature/bug/task description and distill it into a complete plan with requirements, BDD user stories, sprint ordering, and **DoD criteria written so that each task or sprint can be handed to `/goal <condition>` in Claude Code and run autonomously until the condition is met**.
 
+## Synthesis principles (ADR-050)
+
+Three patterns shape every plan you write — they are *our* implementations of ideas learned from the community, not optional flavour:
+
+- **Domain glossary first (`CONTEXT.md`).** If the project has a `CONTEXT.md` (per-repo ubiquitous-language glossary), read it before anything and use its exact vocabulary throughout the plan — entities, actions, statuses. The glossary + the stack pack together are the project's working context. If absent, propose seeding one in §7 (Decisões pendentes).
+- **Tracer-bullet vertical slices.** Decompose sprints/tasks by **end-to-end vertical slices** that cut through every layer (DB → service → API → UI) and ship something demonstrable — NOT horizontal layers ("all backend, then all frontend"). Each slice is independently shippable and gated.
+- **Deep modules (Ousterhout).** In modeling, prefer **deep modules**: a simple, stable, testable interface hiding substantial functionality. Flag **shallow modules** (interface as wide as the implementation, pass-through) as a smell to consolidate.
+
 ## Flow
 
-1. **Understanding**: objective, personas, flows, criteria, copywriting, constraints. Inspect existing code.
+1. **Understanding**: read `CONTEXT.md` (domain glossary) if present and adopt its vocabulary; then objective, personas, flows, criteria, copywriting, constraints. Inspect existing code.
 2. **Requirements**:
    - **FR** (functional) — what the system does.
    - **NFR** (non-functional) — performance, security, UX.
    - **BR** (business rules) — validations, policies.
    - **IR** (implicit) — permissions, audit, pagination, loading, responsiveness, empty states.
-3. **Modeling**: entities + attributes, relationships, detailed flows, technical mapping (endpoints, components, migrations).
+3. **Modeling**: entities + attributes, relationships, detailed flows, technical mapping (endpoints, components, migrations). **Sketch the modules** you will build/modify and mark each **deep** (simple interface, encapsulated complexity — preferred) or **shallow** (pass-through — consolidate). Use the `CONTEXT.md` vocabulary for module + entity names.
 4. **BDD User Stories**: Given/When/Then for happy path AND edge cases. Priority (S/M/L) and estimate.
-5. **Sprints**: tasks ordered with dependencies.
+5. **Sprints**: tasks ordered with dependencies, decomposed as **tracer-bullet vertical slices** — each task/slice cuts end-to-end (DB → service → API → UI as applicable) and is independently demonstrable + gated, never a horizontal layer.
 6. **Risks and pending items**: ambiguities (mark as "ask the client"), `tech-lead` decisions.
 7. **Goal-ready DoD**: for every task and every sprint, write a Definition of Done that a `/goal` evaluator (Haiku by default) can verify objectively from command output or file inspection. See §"Goal-ready output rules" below.
 8. **Generate**: `docs/plans/PLAN_<NAME>.md` following the canonical structure (§"Plan structure").
@@ -100,11 +108,12 @@ The generated `docs/plans/PLAN_<NAME>.md` must have these sections in this order
 
 ## 5. Sprints
 ### Sprint 1 — <tema>
-- Tasks (em ordem de dependência):
-  1. T-001 <descrição>
-     - Cobre US-001, US-002
+- Tasks = tracer-bullet vertical slices (cada uma corta DB→service→API→UI e é demonstrável):
+  1. T-001 <slice end-to-end, ex: "criar produto: migration + endpoint POST + tela mínima de cadastro">
+     - Cobre US-001 (happy path da fatia)
+     - Módulos: <deep: X | shallow a consolidar: Y>
      - DoD: <condição machine-checkable>
-  2. T-002 ...
+  2. T-002 <próxima fatia vertical, ex: "listar produtos: query + GET + tela de listagem">
 
 ### Sprint 2 — ...
 
@@ -165,6 +174,9 @@ retornou GO.
 6. **§8 `/goal` block ends the file.** Always present, never empty. If the plan has a single sprint, you still emit one sprint-level `/goal` plus one final goal.
 7. **No AI/Claude/Anthropic/LLM references in the plan prose.** The PLAN must read as written by the engineering team. Same restriction as commits.
 8. **Filename**: `docs/plans/PLAN_<NAME_KEBAB_CASE>.md`. No spaces, no accents in filename — slug derived from the feature name.
+9. **Tracer-bullet decomposition (ADR-050).** Sprints/tasks are vertical end-to-end slices, never horizontal layers. A task that touches only one layer must be justified (e.g. a pure migration) or merged into a slice.
+10. **Deep modules (ADR-050).** §3 marks each module deep/shallow; shallow modules are flagged for consolidation, not shipped silently.
+11. **Domain glossary (ADR-050).** If `CONTEXT.md` exists, the plan uses its vocabulary verbatim; if absent, §7 proposes seeding it.
 
 ## Interface
 

package/.claude/agents/code-reviewer.md

@@ -77,6 +77,11 @@ For any check above, the **STACK CONTEXT pack overrides** when more specific (e.
 
 ## 4. Cross-cutting checks (universal)
 
+### Design — deep modules (ADR-050)
+- Prefer **deep modules**: simple, stable interface hiding substantial functionality.
+- Flag **shallow modules** as MINOR/MAJOR: interface as wide/complex as the implementation, pure pass-through wrappers, or a class that just forwards to another. Recommend consolidation.
+- New names match the project's `CONTEXT.md` glossary (if present) — flag vocabulary drift as MINOR.
+
 ### Security (delegate hard cases to `security-engineer`)
 - Token / password / PII not logged.
 - CORS not `permitAll` in production.

package/.claude/agents/stack-resolver.md

@@ -24,15 +24,16 @@ Read project's CLAUDE.md, parse `## Project Identity`, identify Primary stack, l
 6. **Read the pack**:
    - If pack exists -> Read it -> return rendered STACK CONTEXT block (see §Output below).
    - If pack absent -> **hard-fail** with `PACK_MISSING_ERROR` (see §Hard-fail protocol below). Do NOT silently fall through to defaults. Do NOT invent a pack.
-7. **Always emit first-line tag** for validation by invoking skill:
-   `[STACK: <lang>/<framework>-<major> | PACK: loaded|none]`
+7. **Read the domain glossary (ADR-050)**: check the project root for `CONTEXT.md` (per-repo ubiquitous-language glossary). If present, read it and append a `DOMAIN GLOSSARY` section to the output so downstream agents use the project's exact vocabulary. If absent, note `Domain glossary: none (suggest seeding CONTEXT.md)` — non-fatal.
+8. **Always emit first-line tag** for validation by invoking skill:
+   `[STACK: <lang>/<framework>-<major> | PACK: loaded|none | GLOSSARY: present|none]`
 
 ## Output format
 
 When pack loaded:
 
 ```
-[STACK: java/spring-boot-3 | PACK: loaded]
+[STACK: java/spring-boot-3 | PACK: loaded | GLOSSARY: present]
 
 === STACK CONTEXT ===
 Language: java
@@ -43,6 +44,9 @@ Pack path: .claude/stacks/java/spring-boot-3.md
 
 === STACK RULES (inline — do not Read again) ===
 <full pack content, including frontmatter, all 10 sections>
+
+=== DOMAIN GLOSSARY (CONTEXT.md — use this vocabulary) ===
+<full CONTEXT.md content if present, else: "none — suggest seeding CONTEXT.md">
 === END STACK CONTEXT ===
 ```
 
@@ -91,6 +95,7 @@ When the pack is absent, before emitting `PACK_MISSING_ERROR`:
 5. **No agent dispatch** — this agent is a leaf; invokers (skills) dispatch others based on the resolver's output.
 6. **Hard-fail on missing pack** — no silent fallback. `PACK_MISSING_ERROR` is mandatory. Invokers must stop or present bypass confirmation. This is non-negotiable (ADR-026 T1.2).
 7. **Always suggest nearest packs** — a resolver that returns only "not found" without suggestions violates this contract.
+8. **Domain glossary is non-fatal (ADR-050)** — read project `CONTEXT.md` if present and append it; if absent, note it and proceed. Never hard-fail on a missing glossary (unlike a missing pack).
 
 ## Interface
 

package/.claude/hooks/flow-state.js

@@ -129,6 +129,36 @@ function deriveState(projectRoot) {
     // docs/plans/ does not exist — no plan artifacts
   }
 
+  // Local-files issue layer (ADR-050): .scratch/<feature>/ is an OPTIONAL,
+  // governed alternative to docs/ artifacts. A PRD.md counts as discovery; an
+  // issues/ dir with at least one issue counts as a plan. So governance still
+  // holds for projects that use the issue-style local files instead of docs/.
+  try {
+    const scratch = path.join(root, '.scratch');
+    for (const feat of fs.readdirSync(scratch)) {
+      const featDir = path.join(scratch, feat);
+      let isDir = false;
+      try { isDir = fs.statSync(featDir).isDirectory(); } catch { /* skip */ }
+      if (!isDir) continue;
+      if (!discoveryArtifact && fs.existsSync(path.join(featDir, 'PRD.md'))) {
+        discoveryArtifact = path.join(featDir, 'PRD.md');
+        if (!activeFeature) activeFeature = feat;
+      }
+      if (!planArtifact) {
+        const issuesDir = path.join(featDir, 'issues');
+        try {
+          const issues = fs.readdirSync(issuesDir).filter((f) => f.endsWith('.md'));
+          if (issues.length > 0) {
+            planArtifact = path.join(issuesDir, issues.sort()[0]);
+            if (!activeFeature) activeFeature = feat;
+          }
+        } catch { /* no issues/ dir */ }
+      }
+    }
+  } catch {
+    // .scratch/ does not exist — no local-files issue artifacts
+  }
+
   // Determine stage
   let stage = 'none';
   if (planArtifact) {

package/.claude/skills/stack-discovery/SKILL.md

@@ -108,6 +108,13 @@ Use `Edit` para substituir SOMENTE a seção `## Project Identity` em `CLAUDE.md
    > "Pack `.claude/stacks/java/spring-boot-5.md` não existe. Disparando `create-stack-pack` para gerar antes de continuar."
    Depois que `create-stack-pack` retorna, feche com o output normal.
 
+### Step 7 — Seed CONTEXT.md (domain glossary — ADR-050)
+
+Se o projeto **não** tem `CONTEXT.md` no root, ofereça semear a partir do template:
+> "Quer que eu crie um `CONTEXT.md` (glossário de domínio) a partir do template? Os agents usam o vocabulário dele em planos/issues/código."
+
+Se **sim**: copie `.claude/CONTEXT.template.md` para `CONTEXT.md` no root e pré-preencha o que já souber da sabatina (domínio em 1 parágrafo + 2-3 termos do glossário). Deixe o resto como placeholder pro user completar. Não bloqueia o fim da skill (opcional).
+
 ## 5. Inviolable rules
 
 1. **Sabatina conversacional, opt-in.** Nunca rode em CI, `sprint-runner`, ou qualquer fluxo autônomo.

package/.claude/skills/to-issues/SKILL.md

@@ -54,13 +54,17 @@ Read the full `PRD_*.md`. Extract from each section:
 
 If `docs/issues/` does not exist, create it. Use `Write` to create `docs/issues/.gitkeep` if needed, then proceed to write the ISSUES file.
 
-### Step 4 — Decompose into issues
+### Step 4 — Decompose into issues (tracer-bullet vertical slices — ADR-050)
 
-Apply the following decomposition rules:
-- One issue per User Story (from the PRD `## User Stories` section).
-- Additional issues for cross-cutting NFRs (security hardening, a11y audit, performance baseline) when they represent distinct, shippable work items.
-- Do NOT create an issue for items listed in `## Out of scope`.
-- Issue granularity: each issue must be completable in one sprint by one developer. Split large stories.
+Decompose by **tracer-bullet vertical slices**, not horizontal layers. Each issue cuts **end-to-end** through every layer it needs (DB → service → API → UI) and ships something demonstrable on its own — never "backend of feature X" + "frontend of feature X" as separate issues.
+
+Rules:
+- **One issue per vertical slice.** A User Story is usually one slice; if a story spans layers, the issue still owns the whole slice end-to-end.
+- **First slice = the thinnest end-to-end path** that proves the architecture (the literal "tracer bullet"). Order issues so the thinnest walking-skeleton slice ships first.
+- Additional issues for cross-cutting NFRs (security hardening, a11y audit, performance baseline) when they are distinct, shippable items.
+- Do NOT create an issue for items in `## Out of scope`.
+- Granularity: each slice completable in one sprint by one developer. Split large stories **by slice** (e.g. "create + read" then "update + delete"), never by layer.
+- Use the project's `CONTEXT.md` glossary vocabulary in titles/bodies if present.
 
 ### Step 5 — Write ISSUES_*.md
 

package/CLAUDE.md

@@ -250,8 +250,21 @@ These thresholds are **universal across stacks**. Stack-specific tooling (JaCoCo
 
 - **Clean Code + SOLID** applied through code, without naming names ostentatiously.
 - **No premature abstraction**. Interface for one implementation = code smell.
+- **Prefer deep modules** (Ousterhout, ADR-050): a **simple, stable interface hiding substantial functionality**. A **shallow module** — interface as wide/complex as its implementation, or a pure pass-through — is a smell; consolidate it. `analyst` marks modules deep/shallow in the plan; `code-reviewer`/`tech-lead` flag shallow ones in review.
 - **Never suggest a technology without justification**. Simplest solution = best.
 
+## Project domain glossary — `CONTEXT.md` (ADR-050)
+
+A project MAY ship a root `CONTEXT.md` (per-repo ubiquitous-language glossary — terms, bounded contexts, invariants, naming). When present, **agents read it before exploring code and use its vocabulary verbatim** in plans, issues, code, and tests. `stack-resolver` surfaces it alongside the stack pack (`DOMAIN GLOSSARY` block); together they are the project's working context. Seed one from `.claude/CONTEXT.template.md` (`stack-discovery` offers this). Absent glossary is non-fatal.
+
+## Decomposition — tracer-bullet vertical slices (ADR-050)
+
+Features are decomposed into **end-to-end vertical slices** (DB → service → API → UI) that each ship something demonstrable — never horizontal layers ("all backend, then all frontend"). The thinnest end-to-end slice ships first (the walking skeleton). `analyst` and `to-issues` own this; `sprint-runner` executes slice by slice.
+
+## Optional local-files issue layer — `.scratch/` (ADR-050)
+
+Projects may use an **issue-style local-files layer** instead of (or alongside) the `docs/discovery|prd|plans/` artifacts: one dir per feature at `.scratch/<feature-slug>/` with `PRD.md` and `issues/NN-<slug>.md` (each issue carries a `Status:` line). This is **governed** — `flow-guard` recognizes `.scratch/<feature>/PRD.md` as a discovery artifact and `.scratch/<feature>/issues/*.md` as a plan artifact, so the same prerequisite gating applies. It is an option, not a replacement; the `docs/` file pipeline remains the default.
+
 ## 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):

package/package.json

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