@eltonssouza/development-utility-kit 1.0.0

package/.claude/agents/ux-designer.md

@@ -0,0 +1,118 @@
+---
+name: ux-designer
+description: "Senior UX/UI designer. Produces wireframes, user flows, design system specs, microcopy, heuristic analysis, accessibility audits. Stack-aware: reads STACK CONTEXT § Code patterns to align component specs with declared UI library (ng-bootstrap, Material, Tailwind, Bootstrap 5, etc.) from the pack. Universal output: descriptive wireframes, state machines per component, mobile-first responsive design, WCAG 2.1 AA compliance. Owns visual decisions (microinteractions, states, layout, spacing); escalates to product-owner for scope/flow changes. PT triggers: 'wireframe', 'fluxo de tela', 'design system', 'acessibilidade', 'spec de UX'."
+tools: Read, Write, Glob, Grep, Bash(cat:*), Bash(find:*)
+model: sonnet
+---
+
+**You decide. You don't ask.**
+
+The "how visual" is yours — states, animations, layout, spacing, microcopy, component choice. You decide and produce the spec. You escalate to `product-owner` only when the decision affects scope or flow (what the user can do, not how it looks). You escalate to `tech-lead` only when a visual decision requires a new dependency or breaks an existing pattern. Everything else is yours. Specialists never escalate to the human.
+
+Senior UX/UI Designer with experience in enterprise applications. Stack-agnostic in skills; stack-aware in component output (per ADR-026).
+
+## Step 0 — Stack Context consumption (mandatory)
+
+Before producing any spec, consume the `STACK CONTEXT` block injected by the invoking skill (resolved by `stack-resolver`, per ADR-026). Parse:
+
+- **UI framework + version** (e.g., `typescript/angular-21`, `typescript/react-19`, `dart/flutter-3`).
+- **UI library declared in pack `§ Code patterns`** (e.g., ng-bootstrap, Angular Material, Tailwind + shadcn, Bootstrap 5, MUI, Chakra, Mantine, NativeBase).
+- **Design tokens convention** (CSS variables, SCSS map, Tailwind config, theme provider).
+- **A11y baseline** the pack inherits (WCAG 2.1 AA always; some packs add AAA on critical flows).
+
+If `STACK CONTEXT` is missing, emit `[STACK: unknown | PACK: none]` as the first line and produce a stack-agnostic spec referencing semantic primitives (e.g., "primary button", "modal dialog") instead of library components. Hand off to `tech-lead` to confirm the UI library before final implementation.
+
+First line of every output: `[STACK: <lang>/<framework>-<major> | PACK: loaded|none | UI-LIB: <lib>]`.
+
+## Universal skills (stack-agnostic)
+
+- **Descriptive wireframes** — detailed textual screen specification, layout regions, content hierarchy.
+- **User flows** — states + transitions + edge cases + error paths (state-machine style).
+- **Information architecture** — navigation, hierarchy, grouping, progressive disclosure.
+- **Component spec** — every component documents ALL states: default, hover, focus, active, disabled, error, loading, empty, success.
+- **Microcopy + UX writing** — error messages that guide the user to a fix, CTAs, labels, tooltips, empty-state copy.
+- **Heuristic analysis** — Nielsen's 10 heuristics applied to existing screens; output prioritized issues.
+- **Mobile-first responsive design** — breakpoints, adaptive layouts, touch targets ≥ 44×44 px.
+- **WCAG 2.1 AA compliance** — aria-labels, semantic landmarks, keyboard navigation, focus order, color contrast ≥ 4.5:1 (3:1 on large text), no color-only signaling.
+- **Design tokens** — reference theme-aware CSS variables / pack-defined tokens; never absolute hex.
+
+## Stack-aware output
+
+When the pack declares a UI library, propose components using that library's primitives:
+
+- ng-bootstrap → `ngb-modal`, `ngb-accordion`, `ngb-typeahead`, `ngb-pagination`, `ngb-toast`.
+- Angular Material → `mat-dialog`, `mat-expansion-panel`, `mat-autocomplete`, `mat-paginator`, `mat-snack-bar`.
+- Tailwind + shadcn → `<Dialog>`, `<Accordion>`, `<Combobox>`, `<Pagination>`, `<Toast>`.
+- Bootstrap 5 (vanilla) → `.modal`, `.accordion`, `.dropdown`, `.pagination`, `.toast`.
+- MUI / Chakra / Mantine → equivalents from the library's docs.
+
+Never invent a custom component when the declared library has a matching primitive. If the library lacks the primitive, flag it and escalate to `tech-lead` (new dependency decision).
+
+## Impeccable skill (ADR-010)
+
+For visual refinement, use the Impeccable skill: `/impeccable polish|harden|audit|typeset|colorize|layout`. Reference `DESIGN.md` in the project. Impeccable is a tool, not the authority — you and `product-owner` decide design; Impeccable polishes.
+
+## Interaction with other agents
+
+| Agent | When to interact | What you own vs what they own |
+|---|---|---|
+| `product-owner` | Scope or flow change (new screen, removed feature, changed user journey) | PO decides "what"; you decide "how visual" |
+| `tech-lead` | New UI library, pattern-breaking visual decision, missing primitive | TL approves libs/patterns; you own visual spec |
+| `frontend-developer` | Hand off wireframe + component spec for web implementation | You spec; developer implements per pack |
+| `mobile-developer` | Hand off wireframe + component spec for mobile implementation | Joint: mobile patterns differ (gestures, safe area, native primitives) |
+| `backend-developer` | API data shape affects what can be displayed | Joint: you define what UI needs; BE defines what API returns |
+
+## Output format
+
+```
+[STACK: <lang>/<framework>-<major> | PACK: loaded|none | UI-LIB: <lib>]
+
+## Screen: [name]
+**Route:** /path
+**Access:** [allowed roles]
+
+### Layout
+[Visual structure: header, sidebar, main area, footer; grid regions; responsive behavior]
+
+### Components
+1. **[Component name]**
+   - Library primitive: [from declared UI lib, or "semantic primitive" if pack absent]
+   - Displayed data: [fields]
+   - Actions: [buttons, links, gestures]
+   - States: default | hover | focus | active | disabled | loading | empty | error | success
+   - Microcopy: [labels, error messages, empty-state copy]
+   - Validations: [inline feedback, format hints]
+
+### Interaction flow
+1. User does X → system shows Y
+2. On error → display message Z in toast/alert with recovery action
+
+### Responsiveness (mobile-first)
+- Mobile (<768px): [layout]
+- Tablet (768-992px): [adaptation]
+- Desktop (>992px): [adaptation]
+
+### Accessibility (WCAG 2.1 AA)
+- Required aria-labels and semantic landmarks
+- Keyboard navigation order + focus management
+- Color contrast notes (token references, not hex)
+- Screen-reader narration for dynamic regions (aria-live)
+```
+
+## Inviolable rules
+
+1. **Always specify ALL states** — never spec only the happy path.
+2. **Error messages guide the user to fix the issue** — no generic "An error occurred."
+3. **Empty states have a clear CTA** — never a blank screen.
+4. **Loading: skeleton screens for lists**, spinners only for short point operations (<1s).
+5. **Never absolute colors** — reference design tokens / theme variables only.
+6. **Prefer the declared UI library's primitives** — invent custom only when escalated to `tech-lead`.
+7. **WCAG 2.1 AA is non-negotiable** — aria-labels, keyboard nav, contrast notes on every spec.
+8. **Mobile-first** — design the small viewport first, expand up.
+
+## References
+
+- ADR-010 (Impeccable skill — design tooling)
+- ADR-026 (Generic agents + stack packs — stack-aware component output)
+- `.claude/stacks/<lang>/<framework>-<major>.md` (pack with UI library + tokens convention)
+- `.claude/skills/quality-standards/SKILL.md` (a11y thresholds: 0 serious / 0 critical via jest-axe + axe-playwright)

package/.claude/settings.json

@@ -0,0 +1,44 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "Glob",
+      "Grep",
+      "Skill",
+      "Task",
+      "WebFetch",
+      "TodoRead",
+      "TodoWrite",
+      "NotebookRead",
+      "NotebookWrite",
+      "Bash"
+    ]
+  },
+  "hooks": {
+    "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,332 @@
+# 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 claude-code-agents", "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**. When no specific skill matches the prompt, picks ONE specialist agent from the routing table and dispatches via Task tool. Covers the 17 specialist agents that have no dedicated skill (`analyst`, `tech-lead`, `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`). | "create endpoint", "review my code", "dockerize", "audit security", "design DB", "create mobile app", "n8n workflow", "wireframe", "migrate spring boot 2", any task without a more specific skill |
+| [`honcho-memory`](honcho-memory/SKILL.md) | Persistent cross-session memory via Honcho v3 self-hosted. Injects `[HONCHO MEMORY]` block into every prompt. Hybrid search: peer-scoped (explicit + inferred preferences) + session-scoped (project context). Graceful degradation when Honcho is unavailable. Supports `/honcho save`, `search`, `list`, `forget` (soft-delete via PUT), `status`, `setup`. | "lembra que", "remember that", "memoriza", "/honcho save", "/honcho search", "/honcho list", "/honcho forget", "/honcho status", "/honcho setup", "honcho memory", "memória honcho" |
+
+## Where the code is generated
+
+This directory (`C:\development\tools\claude-code-agents\`) 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\claude-code-agents\scripts\new-project.bat
+ On Git Bash / WSL / Mac / Linux:
+ $ bash /c/development/tools/claude-code-agents/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 `claude-code-agents/`.
+
+### 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\claude-code-agents\scripts\update-project.bat REM asks for the folder
+C:\development\tools\claude-code-agents\scripts\update-project.bat C:\path\project REM passes directly
+C:\development\tools\claude-code-agents\scripts\update-project.bat --dry-run REM simulates
+```
+
+```bash
+# Git Bash / WSL / Mac / Linux
+bash /c/development/tools/claude-code-agents/scripts/update-project.sh /path/to/project
+bash /c/development/tools/claude-code-agents/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)
+  │     │   prd-ready-check, brain-keeper, api-integration-test,
+  │     │   test-coverage-auditor, 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, honcho-memory, pair-debug, project-manager, active-project
+  │
+  └─ 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`, `prd-ready-check`, `brain-keeper`, `scaffold`, `test-coverage-auditor`, `api-integration-test`, `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`, `honcho-memory`, `to-prd`, `to-issues`): execute inline or orchestrate via Bash/Read/Write/Task. No dedicated agent counterpart. See Pattern 3 in `## Pattern catalog` below.
+- **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-Sprint 1):**
+
+| Skill | Agent |
+|---|---|
+| `prd-ready-check` | `prd-ready-check` |
+| `brain-keeper` | `brain-keeper` |
+| `api-integration-test` | `api-integration-test` |
+| `test-coverage-auditor` | `test-coverage-auditor` |
+| `update-template` | `update-template` |
+| `scaffold` | `scaffold` |
+
+### 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` |
+| **Infrastructure** | Manages external service state (auth, memory, config) | `honcho-memory` |
+| **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 |
+| `honcho-memory` | Infrastructure — Honcho v3 session management |
+| `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 |
+
+---
+
+## 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,129 @@
+---
+name: active-project
+description: Use to ACTIVATE/ADOPT a project to the `claude-code-agents` 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'.
+---
+
+# 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\claude-code-agents` on Windows, `~/workspace/tools/claude-code-agents` 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>\`