@eltonssouza/development-utility-kit 0.10.0

package/.claude/settings.json

@@ -0,0 +1,55 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "Glob",
+      "Grep",
+      "Skill",
+      "Task",
+      "WebFetch",
+      "TodoRead",
+      "TodoWrite",
+      "NotebookRead",
+      "NotebookWrite",
+      "Bash"
+    ]
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/flow-guard.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "json=$(cat); file_path=$(echo \"$json\" | jq -r '.file_path // empty'); if [[ \"$file_path\" =~ \\.(ts|tsx|html|scss|css)$ ]] && command -v npx &>/dev/null && [ -f node_modules/.bin/prettier ]; then npx prettier --write \"$file_path\" 2>/dev/null; fi"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if command -v notify-send &>/dev/null; then notify-send 'Claude Code' 'Needs your attention'; elif command -v osascript &>/dev/null; then osascript -e 'display notification \"Needs your attention\" with title \"Claude Code\"'; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/skills/README.md

@@ -0,0 +1,331 @@
+# Skills — Cowork + Claude Code
+
+> **Breaking change (2026-05-25)**: command layer deleted. Architecture is now 100% Skills + Agents. The `project-manager` skill is the catch-all entry point that routes prompts to the appropriate specialist agent. Specific skills (run-sprint, auto-test-guard, prd-ready-check, grill-me, scaffold, pair-debug, api-integration-test, brain-keeper, test-coverage-auditor, update-template, active-project, caveman) still take priority via keyword match. Standard sprint flow: `analyst` (plan) → `architect` (ADR) → `tech-lead` (approve) → `sprint-runner` (executes Sprint N delegating to `backend-developer` + `frontend-developer` + `database-engineer` in parallel) → `gate-keeper` (gate senior+) → `code-reviewer` → `tech-lead` (merge).
+
+This directory contains the **Skills** that Cowork and Claude Code use to develop fullstack software Java 25+ / Spring Boot 4.0+ / Angular 21+ with this template's standard flow.
+
+Unlike [agents](../agents/) (which are executors invoked via the Task tool), **Skills** are activated automatically based on trigger words in the conversation. Each skill has a `SKILL.md` with frontmatter containing `name` and `description` — the `description` is what the model uses to decide when to trigger the skill.
+
+## Goal
+
+When the user describes a task, Cowork must **deliver it 100% production-ready for deploy**: backend compiles, frontend compiles, tests pass, API responds, screens open with no console errors, and the front consumes the back without failing.
+
+## Available skills
+
+| Skill | Purpose | Triggers with |
+|---|---|---|
+| [`scaffold`](scaffold/SKILL.md) | Unified scaffold entry point — reads `## Project Identity` from CLAUDE.md, runs the appropriate pipeline: fullstack monorepo (Spring Boot 4 + Angular 21 + Docker Compose), backend-only, or frontend-only | "scaffold the project", "scaffold backend", "scaffold frontend", "bootstrap fullstack", "monta o esqueleto", "scaffolda o projeto" |
+| [`sprint-runner`](run-sprint/SKILL.md) | Runs a sprint from the plan — task by task, with checkpoints | "run sprint X", "execute the sprint" |
+| [`api-integration-test`](api-integration-test/SKILL.md) | Boots backend + frontend, validates integration with curl + Chrome MCP | "test integration", "smoke", "validate flow" |
+| [`gate-keeper`](auto-test-guard/SKILL.md) | At the end of each task: **generates** the automated tests for the new code (JUnit+Mockito+Testcontainers, Jest+Testing Library, Playwright) and **runs the full project regression suite**. Blocks the task if any test breaks. | "run the tests", "generate the tests", "test everything", "full suite", "ensure nothing broke", "auto-test" |
+| [`test-coverage-auditor`](test-coverage-auditor/SKILL.md) | Audits test coverage, flags technical debt from manual verification, updates `tech-debt.md`. Mandatory gate inside `prd-ready-check`. | "audit the tests", "test debt?", "coverage ok?", "list what has no test" |
+| [`prd-ready-check`](prd-ready-check/SKILL.md) | Final production gate — tests, builds, lint, E2E, security | "PRD-ready?", "can we deploy?", "DoD" |
+| [`pair-debug`](pair-debug/SKILL.md) | Hypothesis-driven debug loop: state symptom → formulate hypotheses → probe one at a time → confirm cause → fix minimal → write test. Bans "try and see" approach. | "pair debug", "investigate this bug", "find the root cause", "why is this not working" |
+| [`grill-me`](grill-me/SKILL.md) | Discovery interview — one question at a time, with recommendation, until requirements are clear. Persists conclusions to `docs/plans/PLAN_*.md` or ADR. | "grill me", "interview me about", "stress-test the plan", "discover requirements with me" |
+| [`brain-keeper`](brain-keeper/SKILL.md) | Upon completing a PLAN_*: records history in the Obsidian vault (`docs/brain/`) — daily, feature, ADR, bug, tech-debt + updates MOC. Provisions `.obsidian/` with per-folder color snippet on first run. | End of PLAN_*; "record in the brain", "update brain", "log of the day", "close feature in vault" |
+| [`update-template`](update-template/SKILL.md) | Adopts or synchronizes an EXISTING project with the latest version of the template (merge with backup) | "update the template", "bring the new skills", "sync with development-utility-kit", "adopt the template here" |
+| [`active-project`](active-project/SKILL.md) | Path-driven, non-interactive adoption of a project to the template — `/active-project <path>`. Fast lane of `update-template` (no preview/checkpoint). Preferred for scripted batch adoptions. | "/active-project `<path>`", "ativar projeto em `<path>`", "adota o projeto `<path>`", "aplica o template em `<path>`" |
+| [`caveman`](caveman/SKILL.md) | Telegraphic output style — drops articles, filler, pleasantries. 65-75% fewer tokens. Always active; adjustable via "caveman lite\|full\|ultra" or "stop caveman". | Passive (always active); "caveman lite", "caveman ultra", "stop caveman" |
+| [`to-prd`](to-prd/SKILL.md) | Transforms a `DISCOVERY_*.md` into a Product Requirements Document. Requires `grill-me` to have run first. Produces `docs/prd/PRD_*.md` with six required sections: Overview, Goals, User Stories (prose), Functional Requirements, Non-functional Requirements, Out of scope. Idempotent. Opt-in only — never auto-triggered. | "to-prd", "gera PRD", "cria PRD", "generate PRD", "create PRD" |
+| [`to-issues`](to-issues/SKILL.md) | Decomposes a `PRD_*.md` into trackable GitHub issues. Requires `to-prd` to have run first. Produces `docs/issues/ISSUES_*.md` with `[ISSUE-N]` blocks (Labels, Body, Acceptance criteria) ready for `gh issue create`. Idempotent. Opt-in only — never auto-triggered. | "to-issues", "quebra em issues", "gera issues", "break into issues", "generate issues" |
+| [`project-manager`](project-manager/SKILL.md) | **Catch-all fallback router + orchestrator** (per ADR-033). Three modes: **ROUTE** (1 domain -> 1 specialist via Task tool), **ORCHESTRATE** (2-5 domains -> mini-plan inline + parallel Task calls, no PLAN_*.md), **ESCALATE** (>5 subtasks or formal plan needed -> grill-me -> analyst -> sprint-runner). Covers the 17 specialist agents (`analyst`, `tech-lead`, `backend-developer`, `frontend-developer`, `code-reviewer`, `database-engineer`, `devops-engineer`, `mobile-developer`, `n8n-specialist`, `product-owner`, `qa-engineer`, `security-engineer`, `ux-designer`, `migrator`, `release-engineer`, `auditor`). | "create endpoint", "review my code", "dockerize", "audit security", "design DB", "create mobile app", "n8n workflow", "wireframe", "migrate spring boot 2", ad-hoc multi-domain <=5 subtasks ("CRUD products", "back + front pequenos"), any task without a more specific skill |
+
+## Where the code is generated
+
+This directory (`C:\development\tools\development-utility-kit\`) is the **TEMPLATE** — it is not where Java/Angular projects live. The skills here are copied to each new project.
+
+### Canonical projects directory
+
+Every fullstack project generated by this template should live in:
+
+```
+C:\development\source\projects\<project-name>\
+```
+
+This is the default destination — do not use other folders without justification recorded in an ADR. `bootstrap-project.sh` and the `scaffold` skill assume this path.
+
+### End-to-end flow, from zero to deploy
+
+```
+1. Create the project (interactive wrapper — recommended)
+ On Windows (double-click or prompt):
+ > C:\development\tools\development-utility-kit\scripts\new-project.bat
+ On Git Bash / WSL / Mac / Linux:
+ $ bash /c/development/tools/development-utility-kit/scripts/new-project.sh
+
+ The wrapper asks:
+ - Project name (kebab-case)
+ - Type: [1] Backend Java | [2] Frontend | [3] Fullstack
+ - If Frontend: [1] Angular 21 | [2] HTML + Vite Vanilla
+
+ Then creates it in C:\development\source\projects\<name>\ and
+ opens Claude Code directly in the folder.
+
+ (Non-interactive alternative:
+ bash .../scripts/bootstrap-project.sh my-app C:/development/source/projects \
+ --tipo=fullstack --frontend-stack=angular)
+
+2. First instruction in Cowork/Claude Code (the right skill is fired by the type)
+
+3. First instruction (empty project)
+ Any type → "scaffold the project" → triggers scaffold skill → dispatches to scaffold agent
+
+ The scaffold agent reads `## Project Identity` in the project's `CLAUDE.md` to decide
+ what to generate (backend | frontend | fullstack). Type is injected there by bootstrap-project.sh.
+
+4. Subsequent conversations (features)
+ "implement product registration with name, price and stock"
+ → triggers run-sprint
+ → Stage 0: checks backend/pom.xml and frontend/angular.json (OK)
+ → Stage 1 → analyst → docs/plans/PLAN_product-registration.md
+ │ ⏸️ CHECKPOINT
+ → Stage 2 → (architecture) → ADR if any new decision
+ │ ⏸️ CHECKPOINT
+ → Stage 3 → run-sprint → backend-developer + frontend-developer
+ │ (code goes to backend/src/main/java/... and frontend/src/app/...)
+ → Stage 4 → api-integration-test (boots back+front, curl + Chrome MCP)
+ │ ⏸️ CHECKPOINT
+ → Stage 5 → prd-ready-check (GO / NO-GO with mvn test, npm test, builds, E2E)
+ │ ⏸️ CHECKPOINT
+ → Stage 6 → brain-keeper (records daily + feature + ADR + tech-debt + MOC in docs/brain/)
+ │ ⏸️ CHECKPOINT
+ → Stage 7 → commit + PR
+```
+
+**Summary**: the entry point is `new-project.bat` (or `.sh`). It creates the structure in `C:\development\source\projects\<name>\` and opens Claude Code. From there on, the skills do all the work — the code is never generated in `development-utility-kit/`.
+
+### Adoption/update flow (existing project)
+
+If you already have a project and want to **bring it into the template's standard** (or update with new skills when the template evolves), use `update-project`. Two equivalent paths:
+
+**(a) Outside the project — interactive wrapper**
+
+```cmd
+REM Windows
+C:\development\tools\development-utility-kit\scripts\update-project.bat REM asks for the folder
+C:\development\tools\development-utility-kit\scripts\update-project.bat C:\path\project REM passes directly
+C:\development\tools\development-utility-kit\scripts\update-project.bat --dry-run REM simulates
+```
+
+```bash
+# Git Bash / WSL / Mac / Linux
+bash /c/development/tools/development-utility-kit/scripts/update-project.sh /path/to/project
+bash /c/development/tools/development-utility-kit/scripts/update-project.sh --dry-run
+```
+
+**(b) Inside the project — skill in Cowork**
+
+Open the project in Cowork and ask:
+
+```
+update the template
+```
+
+The `update-template` skill shows a preview (what will be merged, what will be created) and asks for confirmation before writing anything.
+
+**What the adoption/update does (idempotent, safe to run multiple times)**
+
+1. **Detects the type** of the project by looking at `backend/pom.xml`, `frontend/angular.json`, `frontend/vite.config.*`.
+2. **Merges `.claude/`** — backs up the current one in `.claude.backup-YYYYMMDD-HHMMSS/` and copies the template files on top, **preserving local custom skills/agents** that do not exist in the template.
+3. **Injects the "Project type" block** into `CLAUDE.md` if missing. If it already exists, just checks consistency.
+
+Anything overwritten is backed up. Local files that the template does not have are **never removed**.
+
+## How Cowork triggers skills
+
+Cowork reads the `description` field of the frontmatter. When the user's message matches the trigger words listed there, the skill is automatically triggered and its `SKILL.md` is loaded into the context.
+
+There is no need to call explicitly — just describe the task. If you want to force a specific skill, use `/skill <name>` (Claude Code) or mention explicitly: "use the `analyst` skill".
+
+## Canonical precedence — skill ↔ agent
+
+Two-layer architecture. Commands layer was deleted on 2026-05-25 (replaced by the `project-manager` skill catch-all).
+
+| Layer | Role | Trigger | Owns what |
+|---|---|---|---|
+| **Skill** (`.claude/skills/<name>/SKILL.md`) | **Entry point** | Auto-trigger via `description` (Cowork classifier) OR explicit `/skill <name>` | Orchestration logic, checkpoints, stage → agent mapping |
+| **Agent** (`.claude/agents/<name>.md`) | **Executor** | Invoked by a skill via `Task(subagent_type="<name>", ...)` | System prompt, decision framework, `model:` declaration |
+
+### Runtime hierarchy
+
+```
+USER MESSAGE
+  │
+  ├─ keyword match → specific SKILL
+  │     │
+  │     ├─ Pattern 1 (Facade pair)   → same-name AGENT (executor)
+  │     │   brain-keeper, update-template, scaffold
+  │     │
+  │     ├─ Pattern 2 (Orchestration) → one or more differently-named AGENTs
+  │     │   run-sprint → sprint-runner
+  │     │   auto-test-guard → gate-keeper
+  │     │   grill-me → analyst
+  │     │   to-prd, to-issues → analyst / product-owner
+  │     │
+  │     └─ Pattern 3 (Standalone)    → no agent; executes inline
+  │         caveman, pair-debug, project-manager, active-project,
+  │         prd-ready-check, api-integration-test, test-coverage-auditor
+  │
+  └─ no match → PROJECT-MANAGER SKILL (catch-all fallback)
+                  ↓ analyzes prompt, picks ONE specialist
+                  ↓ Task(subagent_type="<agent>")
+                 AGENT (executor)
+```
+
+### When name overlaps
+
+For names that exist in both skill + agent (`sprint-runner`, `gate-keeper`, `brain-keeper`, `scaffold`, `update-template`), they describe the **same flow**. The skill is the interface contract; the agent is the execution contract. See Pattern 1 in `## Pattern catalog` below.
+
+### When a name exists only in one layer
+
+- **Skill only** (`caveman`, `pair-debug`, `grill-me`, `active-project`, `project-manager`, `to-prd`, `to-issues`, `prd-ready-check`, `api-integration-test`, `test-coverage-auditor`): execute inline or orchestrate via Bash/Read/Write/Task. No dedicated agent counterpart. See Pattern 3 in `## Pattern catalog` below. The last three were demoted to Pattern 3 in ADR-037 (their same-name agents never existed on disk; the calling session executes them inline).
+- **Agent only** (`tech-lead`, `product-owner`, `architect`, `security-engineer`, `database-engineer`, `devops-engineer`, `code-reviewer`, `ux-designer`, `analyst`, `backend-developer`, `frontend-developer`, `qa-engineer`, `mobile-developer`, `n8n-specialist`, `migrator`, `release-engineer`, `auditor`): invoked via Task tool by skills — commonly by `project-manager` (for tasks without a dedicated skill) or by `sprint-runner` (for sprint tasks).
+
+### Required mapping in router skills
+
+Every skill that orchestrates multiple stages MUST declare a `stage → subagent_type` table using actual agent names (from `.claude/agents/`). This prevents the parent (Opus) from billing inline work that should run on Sonnet/Haiku.
+
+---
+
+## Pattern catalog
+
+Three patterns govern every skill/agent pair in the harness. New entries MUST be classified into one of these patterns before being merged.
+
+### Pattern 1 — Facade pair
+
+A skill and an agent share the **same kebab-case name**. The skill is the **interface contract**; the agent is the **execution contract**.
+
+**Interface contract (skill MUST contain):**
+- `## When to trigger` — keyword triggers, user-facing scenarios.
+- `## Prerequisites` — required artifacts/context before invoking.
+- `## Do NOT use for` — scope boundaries.
+- `## Dispatch` — `Task(subagent_type: "<same-name-agent>", ...)` call.
+- `## Handoff` — pointer to the agent for execution rules.
+
+**Interface contract (skill MUST NOT contain):**
+- Step-by-step execution checklist (belongs to the agent).
+- Inline decision framework.
+- Model selection rules.
+
+**Execution contract (agent MUST contain):**
+- Full step-by-step checklist / phases.
+- Decision framework and golden rules.
+- Tool list and model declaration.
+
+**Execution contract (agent MUST NOT contain):**
+- User-facing PT-language trigger phrases in the body (only in frontmatter `description`).
+- Redundant "when to use" prose already in the skill.
+
+**Current instances (post-ADR-037):**
+
+| Skill | Agent |
+|---|---|
+| `brain-keeper` | `brain-keeper` |
+| `update-template` | `update-template` |
+| `scaffold` | `scaffold` |
+
+> `prd-ready-check`, `api-integration-test`, `test-coverage-auditor` were demoted to Pattern 3 (skill-only) by ADR-037 on 2026-05-29 — their same-name agents never existed on disk, and the calling session executes their gates/probes inline.
+
+### Pattern 2 — Orchestration skill
+
+A skill dispatches to **one or more agents with different names**. The skill owns the multi-stage orchestration; each agent owns its execution slice.
+
+**Rules:**
+- The skill's frontmatter `description` lists user-facing triggers.
+- The skill body contains a `stage → subagent_type` mapping table.
+- Each agent in the chain is independent — the skill passes explicit context on each `Task(...)` call.
+
+**Current instances:**
+
+| Skill | Agent(s) dispatched |
+|---|---|
+| `run-sprint` | `sprint-runner` |
+| `auto-test-guard` | `gate-keeper` |
+| `grill-me` | `analyst` |
+| `to-prd` | `analyst`, `product-owner` |
+| `to-issues` | `analyst`, `product-owner` |
+
+> Note: `scaffold` is simultaneously Pattern 1 (skill + same-name agent) and could be considered orchestration when the scaffold agent itself delegates to `backend-developer` / `frontend-developer`. The classification is Pattern 1 — the skill-to-agent boundary is the primary contract.
+
+### Pattern 3 — Standalone skill
+
+A skill with **no companion agent**. It executes its logic inline (Bash, Read, Write, Edit, Task to a generic specialist) without a dedicated executor agent.
+
+**Justification required** — a skill is standalone only when it falls into one of these categories:
+
+| Category | Description | Examples |
+|---|---|---|
+| **Mode/style** | Changes the output style of the parent session, not a task | `caveman` |
+| **Router** | Catch-all dispatcher — by definition has no fixed agent target | `project-manager` |
+| **Inline transform** | Short-lived transformation that doesn't warrant a dedicated agent | `active-project` |
+| **Interview / generation** | Multi-turn interview + file write, no persistent agent needed | `pair-debug`, `to-prd`, `to-issues`, `grill-me`* |
+
+*`grill-me` is listed here for its inline interview phase; its output handoff to `analyst` makes it also Pattern 2. Primary classification: Pattern 2.
+
+**Current instances (pure Pattern 3):**
+
+| Skill | Justification |
+|---|---|
+| `caveman` | Mode — output style toggle |
+| `pair-debug` | Inline transform — hypothesis loop, no persistent executor |
+| `project-manager` | Router — catch-all; fixed agent target undefined by design |
+| `active-project` | Inline transform — fast-lane adoption, no dedicated agent |
+| `prd-ready-check` | Inline gate — production checklist executed in the calling session (per ADR-037); needs Chrome MCP + Bash inline, would lose tools if dispatched to a child |
+| `api-integration-test` | Inline probes — docker compose + curl + Chrome MCP run in the calling session (per ADR-037); dispatch to a child would lose Chrome MCP access |
+| `test-coverage-auditor` | Inline scan — Glob/Grep over source + dailies, writes to tech-debt.md directly (per ADR-037); stateless instruction set |
+
+---
+
+## Decision rules
+
+Rules D1–D4 govern how new skills and agents are classified and when specialist agents are promoted to paired skills.
+
+### D1 — Pattern 1 contract split (enforced at review)
+
+When a skill+agent pair shares a name (Pattern 1), the split between skill (interface) and agent (execution) MUST be enforced. Violations are caught at `code-reviewer` / `tech-lead` review:
+
+- If the skill body contains execution steps, checklists, or `./mvnw` / `npm run` commands → **REJECT**.
+- If the agent body contains PT-language user-facing triggers (outside frontmatter `description`) → **REJECT**.
+
+### D3 — Defer promotion (specialist agents stay agent-only)
+
+Specialist agents (`release-engineer`, `migrator`, `code-reviewer`, `security-engineer`, etc.) remain **agent-only** — routed via `project-manager` catch-all. Promote a specialist to a paired skill only when **both** conditions are met:
+
+1. Telemetry or repeated session history shows direct keyword invocation for this specialist that bypasses `project-manager`.
+2. The specialist has gained a ceremony of **three or more distinct phases** that benefit from a named orchestration entry point.
+
+The following agents are candidates to watch — eligible for promotion if the conditions above are met:
+
+| Agent | Reason to watch |
+|---|---|
+| `release-engineer` | Multi-phase ceremony: version bump → CHANGELOG → tag → push |
+| `migrator` | Multi-phase: audit → plan → migrate → validate |
+| `code-reviewer` | Frequent direct invocation: "review my PR", "review this code" |
+| `security-engineer` | Frequent direct invocation: "audit security", "OWASP scan" |
+
+Promotion decision: `tech-lead` approves after reviewing telemetry.
+
+### D4 — Standalone skills require justification
+
+A new standalone skill (Pattern 3) MUST declare its justification category from the table in `## Pattern catalog — Pattern 3`. Accepted categories: **mode/style**, **infrastructure**, **router**, **inline transform**, **interview/generation**. A skill submitted without a justification category is rejected at `code-reviewer` review.
+
+---
+
+## Claude Code (terminal) usage
+
+Skills auto-trigger via `description` keywords. To force a specific skill, type `/skill <name>` (Claude Code) or mention by name ("use the `analyst` skill"). The `project-manager` skill catches anything that did not match a more specific skill.
+
+## Conventions of each SKILL.md
+
+- **Frontmatter** with `name` (kebab-case) and `description` (rich in trigger words).
+- **Explicit checkpoints** (⏸️) for skills that orchestrate.
+- **Inviolable rules** at the end.
+- **American English** in every instruction.
+
+## Adding a new skill
+
+1. Create the folder: `.claude/skills/<name>/`.
+2. Create `SKILL.md` with the minimal frontmatter (`name`, `description`).
+3. Structure the content following the pattern of existing skills.
+4. Update this README.
+5. Test by triggering via Cowork. 

package/.claude/skills/active-project/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: active-project
+description: Use to ACTIVATE/ADOPT a project to the `development-utility-kit` template in ONE shot — accepts the project path as the FIRST argument and runs `scripts/adopt-project.sh` directly without preview/checkpoint. Triggers when the user types `/active-project <path>` or says "active project at <path>", "activate project <path>", "ativar projeto", "adota o projeto X", "aplica o template no projeto Y", "ativar template em <path>". Same end-result as `update-template`, but path-driven and non-interactive — preferred for scripted batch adoptions. Supports `--dry-run`, `--force-type=<backend|frontend|fullstack>`, `--template=<path>`. Do NOT use to develop features (use run-sprint), scaffold empty projects (use scaffold), or update the current project's template from inside it (use update-template). PT triggers: 'ativar projeto', 'adota o projeto', 'aplica o template', 'ativa o template em', 'ativar projeto em', 'sincronizar template no projeto'.
+tools: Read, Write, Glob, Grep, Bash(bash:*), Bash(git:*)
+model: sonnet
+---
+
+# Active Project — Adopt a project to the template (path-driven, non-interactive)
+
+Always reply in **Brazilian Portuguese**.
+
+---
+
+## 1. When it triggers
+
+Exact invocations:
+- `/active-project /path/to/project`
+- `/active-project /path/to/project --dry-run`
+- `/active-project /path/to/project --force-type=fullstack`
+- `/active-project /path/to/project --template=/alt/template`
+
+Natural-language equivalents:
+- "ativar projeto em `/path`"
+- "adota o projeto em `/path` com template fullstack"
+- "aplica o template no projeto X em modo dry-run"
+
+If the user asks **without a path**, ask for it before running anything.
+
+---
+
+## 2. What it does
+
+Single-shot wrapper around `scripts/adopt-project.sh`:
+
+1. Detects project type (`backend | frontend | fullstack` + stack `angular | vite-vanilla`) from `backend/pom.xml`, `frontend/angular.json`, `frontend/vite.config.*`.
+2. Backs up the existing `.claude/` to `.claude.backup-YYYYMMDD-HHMMSS/`.
+3. Copies the template `.claude/` into the project, preserving local files outside the template.
+4. Copies the template `CLAUDE.md` and appends the **"Identidade deste projeto"** block (project name, type, stack, adoption date).
+5. Copies `.claude-version.json` and flags as outdated when versions diverge.
+6. Reports backup paths, detected type, and any `[WARN]`/`[ERROR]` from the script.
+
+This is the **fast path** of `update-template`: no preview, no checkpoint, no confirmation.
+
+---
+
+## 3. Difference from `update-template`
+
+| | `active-project` (this) | `update-template` |
+|---|---|---|
+| Path | First positional ARG | Current working directory |
+| Preview/checkpoint | NO (direct execution) | YES (interactive) |
+| Best for | Scripts, batch adoptions | Manual flow inside Claude Code with confirmation |
+| Idempotent | YES (same as adopt-project.sh) | YES |
+
+Both ultimately call `scripts/adopt-project.sh` — they share the engine.
+
+---
+
+## 4. Procedure
+
+1. **Parse the user message** to extract:
+   - PROJECT_PATH (first non-flag argument; absolute path expected)
+   - FLAGS (`--dry-run`, `--force-type=<tipo>`, `--template=<path>`)
+2. **Validate** that PROJECT_PATH exists:
+   ```bash
+   [ -d "<PROJECT_PATH>" ] || echo "[ERROR] Pasta nao existe: <PROJECT_PATH>"
+   ```
+   If it does not exist, STOP and tell the user.
+3. **Locate the template** (default: `C:\development\tools\development-utility-kit` on Windows, `~/workspace/tools/development-utility-kit` on Linux/Mac). Override with `--template` if provided.
+4. **Run** via the `terminal` tool:
+   ```bash
+   bash <TEMPLATE>/scripts/adopt-project.sh "<PROJECT_PATH>" [FLAGS]
+   ```
+5. **Capture full stdout/stderr** and surface it to the user in **PT-BR**, including:
+   - Detected (or forced) type
+   - Backup paths created
+   - `[OK]/[WARN]/[ERROR]` messages from the script
+   - The final "Adoption/update finished" block
+   - Whether the project was flagged as outdated (template/project version mismatch)
+6. If the script reports `[WARN] Could not detect project type`, suggest re-running with `--force-type=<backend|frontend|fullstack>`.
+
+---
+
+## 5. Quick Reference
+
+| Case | Command |
+|---|---|
+| Adopt a fullstack project | `bash adopt-project.sh /path/to/project` |
+| Force the type (no code yet) | `bash adopt-project.sh /path --force-type=fullstack` |
+| Simulate without applying | `bash adopt-project.sh /path --dry-run` |
+| Alternative template | `bash adopt-project.sh /path --template=/other/template` |
+
+---
+
+## 6. Pitfalls
+
+- **Path does not exist** → script aborts with `[ERROR] Folder does not exist`. Validate before invoking.
+- **No `backend/` or `frontend/`** → script fails with `[WARN] Could not detect project type`. Use `--force-type=<tipo>` for projects without code yet.
+- **Path with spaces** → always wrap in quotes when building the command.
+- **Already adopted** → script silently creates a backup (`.claude.backup-*`). Mention this to the user.
+- **Output verbosity** → if the user requests "mostre tudo" / "literal output", echo the captured stdout verbatim (do NOT summarize).
+
+---
+
+## 7. Verification
+
+After applying (no `--dry-run`):
+
+1. `<PROJECT_PATH>/.claude/agents`, `<PROJECT_PATH>/.claude/commands`, `<PROJECT_PATH>/.claude/skills` exist.
+2. `<PROJECT_PATH>/CLAUDE.md` contains the block `## Identidade deste projeto`.
+3. `<PROJECT_PATH>/.claude-version.json` matches the template's version (otherwise report as outdated).
+4. The script printed `Adoption/update finished: <project-name>`.
+
+---
+
+## 8. Inviolable rules
+
+1. NEVER infer or invent a `PROJECT_PATH` from context — if the user did not provide one, ASK.
+2. NEVER execute without `--dry-run` if the user explicitly asked for a simulation.
+3. ALWAYS surface `[WARN]`/`[ERROR]` lines verbatim — do not omit them in the summary.
+4. ALWAYS report the backup paths so the user can recover.
+5. If invoked non-interactively (e.g. from a script), prefer non-blocking mode (no interactive prompts).
+
+---
+
+## 9. References
+
+- Engine script: `scripts/adopt-project.sh`
+- Interactive sibling: [`update-template`](../update-template/SKILL.md)
+- Bootstrap (different purpose — creates new projects): [`scaffold`](../scaffold/SKILL.md)
+- Canonical project directory: `C:\development\source\projects\<name>\`

package/.claude/skills/api-integration-test/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: api-integration-test
+description: Use to validate that backend and frontend talk correctly BEFORE the production gate. Triggers on phrases like "test the integration", "validate that the front is calling the API", "spin everything up and test the flow", "smoke test", "verify that the screen actually works", "open the browser and test", "do the quick E2E". This skill brings up the backend (mvn spring-boot:run or docker compose), brings up the frontend (ng serve), hits the endpoints with curl, opens a headless browser via Chrome MCP, runs the main flows, validates the console has no errors, and validates the network has no failing requests. It does not replace prd-ready-check (which is the formal gate); it serves to shorten the feedback loop during implementation. Do NOT use for unit tests (use auto-test-guard) nor for the final production gate (use prd-ready-check). PT triggers: 'testa a integração', 'valida que o front tá chamando a API', 'sobe tudo e testa', 'smoke test', 'verifica se a tela funciona', 'abre o browser e testa', 'faz o E2E rápido'.
+tools: Read, Write, Glob, Grep, Bash(curl:*), Bash(docker:*), Bash(mvn:*), Bash(npm:*)
+model: sonnet
+---
+
+# API Integration Test — End-to-End Validation
+
+Skill that invokes the `api-integration-test` agent. Always reply in **American English**.
+
+---
+
+## When to trigger
+
+- "test the integration", "validate that the front is calling the API"
+- "spin everything up and test the flow", "smoke test"
+- "verify that the screen actually works", "open the browser and test"
+- "do the quick E2E"
+- PT: "testa a integração", "sobe tudo e testa", "verifica se a tela funciona", "faz o E2E rápido"
+
+## 2. When NOT to trigger
+
+## Prerequisites
+
+- `gate-keeper` (auto-test-guard) has run and returned GREEN on the current code.
+- Backend and frontend code compile locally without errors.
+- Docker (or local Postgres/Redis) is available for dependent services.
+- Chrome MCP extension is installed and connected (for browser validation).
+
+---
+
+## Do NOT use for
+
+- Unit or integration tests — use `gate-keeper` (auto-test-guard skill).
+- The final production gate — use `prd-ready-check`.
+- Writing test code — use `qa-engineer` / `backend-developer` / `frontend-developer`.
+
+1. `navigate` to each main screen.
+2. `read_console_messages` — assert zero errors.
+3. `read_network_requests` — assert zero unexpected 4xx/5xx, zero asset 404.
+4. Run minimum CRUD flow: create → list → edit → delete.
+
+## Execution
+
+Standalone skill (Pattern 3 per ADR-037). The calling session executes the smoke E2E inline using the frontmatter `tools:` + Chrome MCP — no Task dispatch (dispatching would lose Chrome MCP access in the child).
+
+### Sequence
+
+1. **Boot backend** — stack-appropriate (`./mvnw spring-boot:run`, `docker compose up -d backend`, `uvicorn`, `go run`, ...) from the pack `## Build & run commands`.
+2. **Boot frontend** — `npm start` / `ng serve` / framework equivalent.
+3. **Curl smoke** — hit each endpoint in the OpenAPI/spec; assert 2xx for happy path + 4xx for known invalid input.
+4. **Browser flow via Chrome MCP**:
+   - `navigate` to each main screen.
+   - `read_console_messages` → assert zero errors.
+   - `read_network_requests` → assert zero unexpected 4xx/5xx, zero asset 404.
+   - Run minimum CRUD: create → list → edit → delete.
+5. **Tear down on exit** — always, even on failure (use `trap` if shelling).
+
+### Inviolable rules
+
+1. **Never "prove it works" by reading code only** — must boot and observe live.
+2. **Zero console errors** is a hard requirement.
+3. **Tear down processes on exit** (`trap` for shell, finally for Node/Python).
+4. **Document tested URLs, methods, responses** in the report.
+5. **Failure returns to a specialist via `project-manager`** — never to the human.
+
+### Output format
+
+```
+API Integration Test — <date> — <project>
+
+Endpoint smoke
+  [OK]   GET  /api/v1/health      → 200
+  [OK]   POST /api/v1/products    → 201 (id=42)
+  [FAIL] GET  /api/v1/products/42 → 500 (NullPointerException at ProductController.java:42)
+
+Browser smoke (Chrome MCP)
+  [OK]   /login          — navigated, console clean
+  [FAIL] /products list  — 404 on chunk-asset.js
+
+Verdict: FAIL
+Routing: backend-developer (NPE on GET /products/{id}) + frontend-developer (asset 404)
+```