@eltonssouza/development-utility-kit 1.0.0

package/dashboard/public/content/docs/skills-reference.en.md

@@ -0,0 +1,500 @@
+# Skills — Complete reference
+
+**Skills** are the entry layer of the `development-utility-kit` harness. Each skill lives in `.claude/skills/<slug>/SKILL.md` and triggers automatically via keyword match on its frontmatter `description`. Unlike **agents** (executors invoked via the `Task` tool, with `model:` declared), skills carry the orchestration logic: they read the request, define checkpoints, map stages to subagents, and dispatch the work.
+
+Master rule: **one entry, one skill, one or more agents**. Specific skills win by keyword match; anything that does not match falls into the `project-manager` router. There is no longer a command layer (removed on 2026-05-25) — only Skill + Agent.
+
+This document covers the 18 official skills of the harness, grouped by purpose. For the agent catalog, see [Agents reference](agents-reference). For the end-to-end flow, see [Pipeline](pipeline). For runtime hooks (`UserPromptSubmit`, `Stop`), see [Hooks reference](hooks-reference).
+
+## Master table
+
+| Skill | PT triggers (samples) | Delegated agent | Primary output |
+|---|---|---|---|
+| `project-manager` | "cria endpoint", "revisa meu código", "auditoria de segurança" | Specialist picked from routing table | `Task(subagent_type=...)` dispatch |
+| `grill-me` | "grill me", "me entrevista sobre", "stress-test o plano" | `analyst` (in long sessions) | `docs/discovery/DISCOVERY_*.md` |
+| `to-prd` | "to-prd", "gera PRD", "cria PRD" | Inline (Sonnet) | `docs/prd/PRD_*.md` |
+| `to-issues` | "to-issues", "quebra em issues", "gera issues" | Inline (Sonnet) | `docs/issues/ISSUES_*.md` |
+| `bootstrap-backend-java` | "scaffolda o backend", "cria backend Java" | `scaffold` | `backend/` Spring Boot 4 + Flyway + compose |
+| `bootstrap-frontend` | "scaffolda o frontend", "cria frontend Angular", "cria frontend Vite" | `scaffold` | `frontend/` Angular 21 or Vite Vanilla |
+| `bootstrap-fullstack` | "cria o esqueleto", "bootstrap fullstack" | `scaffold` | Monorepo `backend/` + `frontend/` + compose |
+| `active-project` | "ativar projeto em `<path>`", "adota o projeto" | `adopt-project.sh` wrapper | Updated `.claude/` + backup |
+| `update-template` | "atualiza o template", "traz as skills novas" | `adopt-project.sh` wrapper | `.claude/` merged with preview |
+| `run-sprint` | "roda a sprint 1", "executa a sprint" | `sprint-runner` → `backend-developer`, `frontend-developer`, `database-engineer`, `gate-keeper` | Code + tests + commit per task |
+| `auto-test-guard` | "roda os testes", "gera os testes", "garante que nada quebrou" | `gate-keeper` | Generated tests + green suite + senior+ gate |
+| `test-coverage-auditor` | "audita os testes", "tem débito de teste?" | `test-coverage-auditor` | Debt report + `architecture/tech-debt.md` |
+| `prd-ready-check` | "tá pronto pra PRD?", "DoD", "gate de prod" | `prd-ready-check` (+ `security-engineer`) | GO / NO-GO |
+| `api-integration-test` | "testa a integração", "smoke", "abre o browser e testa" | `api-integration-test` | curl + Chrome MCP report |
+| `pair-debug` | "vamos debugar", "investiga esse bug", "achar a causa raiz" | Inline; `qa-engineer` for confirming test | Hypothesis → probe → verdict → fix |
+| `brain-keeper` | "registra no cérebro", "atualiza brain", "log do dia" | `brain-keeper` | `docs/brain/` daily + feature + ADR + MOC |
+| `honcho-memory` | "lembra que", "/honcho save", "/honcho search" | `UserPromptSubmit` / `Stop` hooks | Injected `[HONCHO MEMORY]` block |
+| `caveman` | Always on; "caveman lite/full/ultra", "stop caveman" | Inline (style) | Telegraphic output (~65-75% fewer tokens) |
+
+---
+
+## Catch-all router
+
+### project-manager
+
+**PT triggers**: "cria endpoint", "implementa controller", "cria componente", "faz a tela", "revisa meu código", "auditoria de segurança", "modela banco", "dockeriza", "setup CI", "cria app mobile", "cria workflow n8n", "refina backlog", "escreve teste", "wireframe", "migra spring boot 2", "bump version", "decisão técnica".
+
+**EN triggers**: "create endpoint", "implement controller", "create component", "review my code", "security audit", "design the database", "optimize query", "dockerize", "setup CI", "create mobile app", "n8n workflow", "refine backlog", "write tests", "wireframe", "migrate from spring boot 2", "release prep", "architecture decision", "analyze this task".
+
+**When to fire**: any development request that does **not** match a specific skill. It is the default entry point — the wildcard that covers the 17 specialist agents without a dedicated skill.
+
+**What it does**: reads the intent, picks ONE specialist from the routing table (`analyst`, `architect`, `backend-developer`, `frontend-developer`, `code-reviewer`, `database-engineer`, `devops-engineer`, `mobile-developer`, `n8n-specialist`, `product-owner`, `qa-engineer`, `security-engineer`, `tech-lead`, `ux-designer`, `migrator`, `release-engineer`, `auditor`), announces the choice in one line, and dispatches via the `Task` tool. Never orchestrates multiple agents — that is what `run-sprint` is for.
+
+**Delegated agent**: variable, per internal routing table.
+
+**Output / artifacts**: `Task(subagent_type="<agent>", description="...", prompt="...")` call. Final artifacts (code, ADR, report) come from the chosen specialist.
+
+**Prerequisites**: none — it is the catch-all.
+
+**When NOT to fire**: when a specific skill matches (`run-sprint`, `auto-test-guard`, `prd-ready-check`, `grill-me`, `bootstrap-*`, `pair-debug`, `api-integration-test`, `brain-keeper`, `test-coverage-auditor`, `update-template`, `active-project`, `caveman`). Specific skills always win by specificity.
+
+---
+
+## Discovery → PRD → Issues
+
+### grill-me
+
+**PT triggers**: "grill me", "me entrevista sobre", "me interroga", "stress-test o plano", "me questiona até entender", "descobre os requisitos comigo", "rubber duck".
+
+**EN triggers**: "grill me", "interview me about", "stress-test the plan", "discover requirements with me".
+
+**When to fire**: discovery phase, before PLAN or ADR. When the user wants to stress-test an idea, surface hidden requirements, or explore a decision tree before committing with `analyst`.
+
+**What it does**: interviews the user one decision at a time. For each question, brings a recommended answer for the user to simply confirm. When the answer can come from the code, uses `Read`/`Grep`/`Glob`/`git log` instead of asking. Persists conclusions in `DISCOVERY_*.md` so the 45 minutes of interview are never lost.
+
+**Delegated agent**: runs inline in Sonnet; in long sessions may dispatch to `analyst`.
+
+**Output / artifacts**: `docs/discovery/DISCOVERY_<NAME>.md` (input for `to-prd`); optionally a PLAN seed or ADR draft.
+
+**Prerequisites**: engaged human (ADR-011). Never run in `sprint-runner`, CI, or unattended sessions.
+
+**When NOT to fire**: inside `sprint-runner` / `run-sprint`; to implement code (use `run-sprint`); to generate tests (`auto-test-guard`); for a single-answer clarification (use `AskUserQuestion` directly).
+
+### to-prd
+
+**PT triggers**: "to-prd", "gera PRD", "cria PRD".
+
+**EN triggers**: "to-prd", "generate PRD", "create PRD", "turn discovery into PRD".
+
+**When to fire**: explicit opt-in, **after** `grill-me` produced a `DISCOVERY_*.md`. Never auto-invoked.
+
+**What it does**: reads `docs/discovery/DISCOVERY_*.md` and produces a prose PRD with exactly six sections: Overview, Goals, User Stories (prose, no BDD), Functional Requirements, Non-functional Requirements, Out of scope. Idempotent — re-running overwrites without side effects. Does not emit FR-NNN numbered lists or sprint sections (that is `analyst`'s job).
+
+**Delegated agent**: inline in Sonnet (`tools: Read, Write, Glob`).
+
+**Output / artifacts**: `docs/prd/PRD_<NAME>.md`.
+
+**Prerequisites**: existing `docs/discovery/DISCOVERY_*.md`.
+
+**When NOT to fire**: without DISCOVERY (refuses and instructs running `grill-me`); to produce a technical PLAN (use `analyst`); to break into issues (use `to-issues`); to implement (use `run-sprint`).
+
+### to-issues
+
+**PT triggers**: "to-issues", "quebra em issues", "gera issues".
+
+**EN triggers**: "to-issues", "break into issues", "generate issues", "create issues from PRD".
+
+**When to fire**: explicit opt-in, **after** `to-prd` produced a `PRD_*.md`. Never auto-invoked.
+
+**What it does**: reads `docs/prd/PRD_*.md` and decomposes it into an `ISSUES_*.md` where each `[ISSUE-N]` block carries Title / Labels / Body / Acceptance criteria, ready for `gh issue create`. Idempotent.
+
+**Delegated agent**: inline in Sonnet (`tools: Read, Write, Glob`).
+
+**Output / artifacts**: `docs/issues/ISSUES_<NAME>.md`.
+
+**Prerequisites**: existing `docs/prd/PRD_*.md`.
+
+**When NOT to fire**: without PRD (refuses and instructs running `to-prd`); to implement (use `run-sprint`); to produce a technical PLAN (use `analyst`); to validate readiness (use `prd-ready-check`).
+
+---
+
+## Bootstrap and scaffolding
+
+### bootstrap-backend-java
+
+**PT triggers**: "scaffolda o backend", "cria backend Java", "cria o esqueleto do backend", "bootstrap backend", "monta o Spring Boot", "gera o pom.xml", "primeiro setup do backend".
+
+**EN triggers**: "scaffold the backend", "create Java backend", "bootstrap backend", "set up Spring Boot".
+
+**When to fire**: first conversation of a **backend-only** project created via `new-project.bat` or `bootstrap-project.sh` with `--tipo=backend`. Confirms the type by reading the project's `CLAUDE.md`.
+
+**What it does**: generates `backend/` via Spring Initializr (Spring Boot 4.0+, Java 25+), `application.yml` with dev/prod profiles, initial Flyway migration, `docker-compose.yml` with PostgreSQL 17 + Redis 7 + Mailhog, README. Asks for base package, port, DB, Spring AI, OAuth2, messaging before creating.
+
+**Delegated agent**: `scaffold` (Haiku — mechanical work).
+
+**Output / artifacts**: `backend/pom.xml`, `backend/src/main/java/...`, `backend/src/main/resources/application.yml`, `backend/src/main/resources/db/migration/V1__init.sql`, `docker-compose.yml`.
+
+**Prerequisites**: project under `C:\development\source\projects\<name>\`; `CLAUDE.md` with `Project type: backend`; `backend/pom.xml` does not yet exist.
+
+**When NOT to fire**: fullstack project (use `bootstrap-fullstack`) or frontend (`bootstrap-frontend`); `backend/pom.xml` already exists (use `run-sprint`).
+
+### bootstrap-frontend
+
+**PT triggers**: "scaffolda o frontend", "cria frontend Angular", "cria o frontend Vite", "cria o esqueleto do front", "bootstrap frontend", "monta o Angular".
+
+**EN triggers**: "scaffold the frontend", "create Angular frontend", "create the Vite frontend", "bootstrap frontend".
+
+**When to fire**: first conversation of a **frontend-only** project. Detects the stack by reading `CLAUDE.md` — `angular` or `vite-vanilla`.
+
+**What it does**: for Angular, generates a standalone + Signals + ng-bootstrap + Jest + ESLint + Playwright project with functional interceptors (auth, error→ProblemDetail, correlation-id) and `core/`/`shared/`/`features/` structure. For Vite Vanilla, generates HTML + Vite + Bootstrap 5 CDN + fetch wrapper + Vitest. In both cases, configures backend proxy and environments.
+
+**Delegated agent**: `scaffold` (Haiku).
+
+**Output / artifacts**: `frontend/package.json`, `frontend/src/`, `frontend/proxy.conf.json` (Angular), `frontend/vite.config.ts` (Vite), Playwright smoke spec.
+
+**Prerequisites**: `CLAUDE.md` with `Project type: frontend` and `Frontend stack:` set; `frontend/package.json` absent.
+
+**When NOT to fire**: fullstack or backend project; `frontend/` already scaffolded.
+
+### bootstrap-fullstack
+
+**PT triggers**: "cria novo projeto", "iniciar projeto", "scaffolda backend e frontend", "cria o esqueleto", "bootstrap fullstack", "monta o monorepo", "primeiro setup".
+
+**EN triggers**: "create new project", "start project", "scaffold backend and frontend", "create the skeleton", "bootstrap fullstack", "set up the monorepo".
+
+**When to fire**: first conversation of a **fullstack** project with no Java/Angular code yet. Verifies that neither `backend/pom.xml` nor `frontend/angular.json` exist.
+
+**What it does**: generates a monorepo with `backend/` (Spring Boot 4 via Spring Initializr), `frontend/` (Angular 21 via `ng new`), `docker-compose.yml` with PostgreSQL + Redis + Mailhog + Prometheus + Grafana, `.env.example`, README. Three phases (backend / frontend / infra) loaded on demand from `resources/`.
+
+**Delegated agent**: `scaffold` (Haiku).
+
+**Output / artifacts**: full monorepo at `C:\development\source\projects\<name>\`.
+
+**Prerequisites**: canonical folder; empty `backend/` and `frontend/`.
+
+**When NOT to fire**: project already has backend and frontend (use `run-sprint`); backend-only (`bootstrap-backend-java`) or frontend-only (`bootstrap-frontend`).
+
+### active-project
+
+**PT triggers**: "ativar projeto em `<path>`", "adota o projeto", "aplica o template", "ativa o template em", "sincronizar template no projeto".
+
+**EN triggers**: "/active-project `<path>`", "active project at `<path>`", "activate project `<path>`".
+
+**When to fire**: when the user passes an explicit path and wants one-shot adoption with no preview or checkpoint. Preferred for scripted batches.
+
+**What it does**: one-shot wrapper of `scripts/adopt-project.sh`. Detects type (backend/frontend/fullstack + stack), backs up `.claude/` to `.claude.backup-YYYYMMDD-HHMMSS/`, copies the template, injects the "Identidade deste projeto" block into `CLAUDE.md`, and copies `.claude-version.json`. Supports `--dry-run`, `--force-type=<type>`, `--template=<path>`.
+
+**Delegated agent**: none — calls the script directly via Bash.
+
+**Output / artifacts**: updated `.claude/`; timestamped backup; `CLAUDE.md` with Project Identity filled in; `.claude-version.json`.
+
+**Prerequisites**: project path passed as the first argument.
+
+**When NOT to fire**: to create a new project (use `bootstrap-*`); to update the current project from inside it (use `update-template`, which has preview); to implement features (use `run-sprint`).
+
+### update-template
+
+**PT triggers**: "atualiza o template", "sync com claude-code-agents", "traz as skills novas", "atualiza as skills", "reimporta o template", "adota o template neste projeto".
+
+**EN triggers**: "update the template", "sync with claude-code-agents", "bring in the new skills", "reimport the template".
+
+**When to fire**: running **inside** a project, when you want to sync with the latest harness version with a preview before applying.
+
+**What it does**: locates the template (default `C:\development\tools\development-utility-kit`), detects the project type, shows a diff preview, asks for confirmation, then runs `scripts/adopt-project.sh`. Backs up `.claude/`, merges preserving local files, injects the "Project type" block into `CLAUDE.md` if missing, optionally runs `retrofit-frontend-quality.sh`.
+
+**Delegated agent**: `update-template` (Haiku — mechanical sync).
+
+**Output / artifacts**: merged `.claude/`; `.claude.backup-*/`; change report.
+
+**Prerequisites**: being inside a project previously adopted (or about to be adopted).
+
+**When NOT to fire**: to create a new project (`bootstrap-*`); to update project code (`run-sprint`); for batch adoption without preview (`active-project`).
+
+---
+
+## Sprint execution
+
+### run-sprint
+
+**PT triggers**: "roda a sprint 1", "executa a sprint", "implementa as tarefas da sprint", "bora codar essa sprint".
+
+**EN triggers**: "run sprint 1", "execute sprint 2 of plan X", "implement the current sprint tasks", "let's code this sprint".
+
+**When to fire**: when an approved plan exists at `docs/plans/PLAN_*.md` and the user asks to execute a specific sprint. This skill **consumes** the plan, it does not create one.
+
+**What it does**: reads `docs/plans/PLAN_<NAME>.md`, locates the indicated sprint, and dispatches each task to the matching specialist via the `Task` tool (NEVER inline — wastes Opus tokens). Task-type → agent mapping: backend Java → `backend-developer`, Angular → `frontend-developer`, schema/index/query → `database-engineer`, RN/Expo → `mobile-developer`, test generation + gate → `gate-keeper`, final record → `brain-keeper`. Supports parallelism when tasks do not share files.
+
+**Delegated agent**: `sprint-runner` (Sonnet) as orchestrator; dispatches in parallel to `backend-developer`, `frontend-developer`, `database-engineer`, `mobile-developer`, `qa-engineer`, `gate-keeper`, `brain-keeper`.
+
+**Output / artifacts**: code under `backend/src/main/java/...` and `frontend/src/app/...`; matching tests; per-task Conventional Commits.
+
+**Prerequisites**: `docs/plans/PLAN_<NAME>.md` approved by `tech-lead`; sprint identified (number or name); project already scaffolded.
+
+**When NOT to fire**: to create the plan (use `analyst`); to validate production readiness (use `prd-ready-check`); for an empty project (use `bootstrap-*` first).
+
+---
+
+## Quality and gate
+
+### auto-test-guard
+
+**PT triggers**: "roda os testes", "gera os testes", "garante que nada quebrou", "valida a tarefa", "roda a regressão", "testa tudo", "suite completa", "confere se não quebrei nada", "fim de tarefa", "cria testes pra essa feature".
+
+**EN triggers**: "run the tests", "generate the tests", "test everything", "full suite", "auto-test", "validate the senior+ gate".
+
+**When to fire**: at the end of every implemented task/feature, automatically inside `run-sprint` or manually by the user.
+
+**What it does**: three steps: (1) generates missing tests for the new code — JUnit 5 + Mockito + Testcontainers on the backend, Jest + Testing Library on the frontend, Playwright for E2E; (2) runs the full regression (`mvn verify`, `npm test`, `npx playwright`); (3) validates the senior+ gate (coverage ≥ 85%, PIT mutation ≥ 70%, SpotBugs/SonarLint without CRITICAL/HIGH, OWASP dependency-check without CVSS ≥ 7.0). Blocks the task if anything fails.
+
+**Delegated agent**: `gate-keeper` (Sonnet) — mandatorily via `Task` tool, never inline. May sub-dispatch to `backend-developer`, `frontend-developer`, `qa-engineer` for non-trivial test authoring.
+
+**Output / artifacts**: generated test files, coverage report, GREEN / BLOCKED verdict with failure list.
+
+**Prerequisites**: implemented code (comes from `sprint-runner` or manual edit).
+
+**When NOT to fire**: to audit test debt (use `test-coverage-auditor`); as the final production gate (use `prd-ready-check`, which assumes this skill already passed).
+
+### test-coverage-auditor
+
+**PT triggers**: "audita os testes", "tem débito de teste?", "cobertura tá ok?", "o que depende de teste manual aqui?", "faz auditoria de cobertura", "lista o que não tem teste", "procura débito de teste".
+
+**EN triggers**: "audit the tests", "is there test debt?", "is coverage ok?", "look for test debt", "list what has no test".
+
+**When to fire**: on explicit request; automatically in Stage 5 of `run-sprint`; as a mandatory prerequisite of `prd-ready-check`.
+
+**What it does**: scans backend code (controllers, services, domain) and frontend code (components, HTTP services, guards), checks for matching automated tests, reads recent dailies and feature notes looking for terms like "tested manually", "checked in the browser", "deployed and tested", and emits a debt report. Updates `architecture/tech-debt.md` and creates notes in `bugs/` for critical items. **Does not write tests** — only flags.
+
+**Delegated agent**: `test-coverage-auditor` (Sonnet).
+
+**Output / artifacts**: report with P0/P1 notes; updated `architecture/tech-debt.md`; notes at `bugs/<slug>.md` for critical debt.
+
+**Prerequisites**: `CLAUDE.md` with project type; existing code to scan.
+
+**When NOT to fire**: to write tests (use `backend-developer` / `frontend-developer` / `api-integration-test`); to run the suite (use `auto-test-guard`).
+
+### prd-ready-check
+
+**PT triggers**: "tá pronto pra PRD?", "pode subir pra produção?", "roda o checklist final", "valida tudo antes do deploy", "roda o gate de prod", "DoD", "definição de pronto".
+
+**EN triggers**: "is it ready for PRD?", "can it ship to production?", "run the final checklist", "DoD", "definition of done", "release check".
+
+**When to fire**: final gate before deploying to production. Does not implement anything — only validates.
+
+**What it does**: runs `mvn test`, `npm test`, `mvn package`, `ng build --configuration=production`, clean lint, Playwright smoke E2E, clean browser console, minimum coverage, no critical vulnerabilities. Invokes `test-coverage-auditor` as a mandatory gate (open P0/P1 = automatic NO-GO). Returns GO or NO-GO with concrete reasons.
+
+**Delegated agent**: `prd-ready-check` (Sonnet) — mandatorily via `Task` tool. Sub-invokes `test-coverage-auditor` and `security-engineer` also via Task.
+
+**Output / artifacts**: GO / NO-GO report with item-by-item checklist.
+
+**Prerequisites**: `auto-test-guard` already green; code integrated and working.
+
+**When NOT to fire**: to implement fixes (use `backend-developer` / `frontend-developer`); to generate tests (use `auto-test-guard`).
+
+### api-integration-test
+
+**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".
+
+**EN triggers**: "test the integration", "validate that the front is calling the API", "spin everything up and test the flow", "smoke test", "open the browser and test".
+
+**When to fire**: validate that backend and frontend talk to each other correctly during implementation, before the formal gate. Shortens the feedback loop.
+
+**What it does**: brings up the backend (`mvn spring-boot:run` or `docker compose`), brings up the frontend (`ng serve`), waits for `/actuator/health` to return UP, hits the endpoints with curl, opens a headless browser via Chrome MCP, runs the main flows, validates that the console has no errors and the network has no failing requests.
+
+**Delegated agent**: `api-integration-test` (Sonnet).
+
+**Output / artifacts**: report with curl output + Chrome MCP screenshots + console error list (if any).
+
+**Prerequisites**: backend and frontend implemented and compiling; external services (DB, cache) available; test credentials provided.
+
+**When NOT to fire**: for unit tests (use `auto-test-guard`); as the final production gate (use `prd-ready-check`).
+
+### pair-debug
+
+**PT triggers**: "vamos debugar", "pair debug", "investiga esse bug", "debug pair", "achar a causa", "investigar a falha", "qual a causa raiz", "descobrir por que", "estranho, não funciona".
+
+**EN triggers**: "pair debug", "investigate this bug", "find the root cause", "why is this not working".
+
+**When to fire**: bug reported whose cause is not obvious — runtime errors, intermittent failures, mysterious 4xx/5xx, data missing from DB after a write, console.error on the front, race conditions.
+
+**What it does**: applies a disciplined 5-phase loop — (1) states the symptom as observed fact, (2) formulates 2-5 hypotheses with confidence, (3) picks ONE cheap probe (curl, log, breakpoint, SELECT, browser console via Chrome MCP), (4) gathers the evidence, (5) accepts or rejects. Repeats until it converges. Bans "try and see" — every code change follows a tested hypothesis.
+
+**Delegated agent**: runs inline in Sonnet. To write the confirming test, dispatches to `qa-engineer` via Task.
+
+**Output / artifacts**: reasoning log (symptom → hypotheses → probes → verdict → fix); regression test reproducing the original bug.
+
+**Prerequisites**: reported symptom (ideally reproducible).
+
+**When NOT to fire**: obvious bug with obvious fix (typo, import, syntax); bug with a solid pre-existing hypothesis; feature not yet implemented (use `run-sprint`); proactive refactor; performance tuning without a symptom (use `database-engineer` or `tech-lead`).
+
+---
+
+## Memory and history
+
+### brain-keeper
+
+**PT triggers**: "registra no cérebro", "atualiza brain", "log do dia", "salva ADR no vault", "fecha feature no brain", "registra histórico", "atualiza obsidian", "encerra sprint no vault".
+
+**EN triggers**: "record in the brain", "update brain", "log of the day", "close feature in brain", "save ADR in vault".
+
+**When to fire**: automatically at Stage 7 of `run-sprint` (after PRD-ready GO) and at sprint close (after `auto-test-guard` green). Manually by the user at the end of any PLAN_*.
+
+**What it does**: records the development history in the Obsidian vault at `docs/brain/`. Creates `daily/YYYY-MM-DD.md`, `features/<slug>.md`, `decisions/ADR-NNN-*.md` (if a new decision happened), `bugs/<slug>.md` (if it was a fix), append in `architecture/tech-debt.md` (if debt was accepted), and updates the MOC (`README.md`). Provisions `docs/brain/` + `.obsidian/` with a per-folder color snippet on first run. Idempotent in WRITE mode.
+
+**Delegated agent**: `brain-keeper` (Sonnet).
+
+**Output / artifacts**: `docs/brain/daily/`, `docs/brain/features/`, `docs/brain/decisions/`, `docs/brain/bugs/`, `docs/brain/architecture/tech-debt.md`, `docs/brain/README.md` (MOC), `docs/brain/.obsidian/snippets/folder-colors.css`.
+
+**Prerequisites**: PLAN_* finished; senior+ gate green.
+
+**When NOT to fire**: to answer history questions (read the vault directly); for trivial tasks.
+
+---
+
+## Style
+
+### caveman
+
+**Triggers**: always on in this project. Adjustable with "caveman lite", "caveman full", "caveman ultra", "stop caveman", "back to normal".
+
+**When to fire**: passive. By default applies ULTRA to code (`.java`, `.ts`, `.py`, `.sh`, `.yml`, `.json`) and LITE/FULL to prose (`.md`, chat).
+
+**What it does**: cuts articles, fillers, and pleasantries, producing telegraphic output with ~65-75% fewer tokens. Does not change technical semantics — only removes fluff. Preserves YAML frontmatter, symbol names, paths, exact commands. Auto-promotes to FULL when the artifact is an ADR, security audit, PRD, post-mortem, or contract/API spec (substance matters).
+
+**Delegated agent**: inline (style applied to all output).
+
+**Output / artifacts**: model output, compressed.
+
+**Prerequisites**: none.
+
+**When NOT to fire**: to suppress error messages, schema details, ADR semantics — caveman only removes filler, never technical substance.
+
+---
+
+## Passive skills (always on)
+
+Two skills do not wait for keyword match — they operate continuously in the background.
+
+### honcho-memory
+
+**PT triggers**: "lembra que", "memoriza", "nunca", "sempre", "/honcho save", "/honcho search", "/honcho list", "/honcho forget", "/honcho status", "/honcho setup", "memória persistente".
+
+**EN triggers**: "remember that", "memorize this", "never do", "always do", "/honcho save", "/honcho search", "/honcho list", "/honcho forget", "/honcho status", "/honcho setup".
+
+**When to fire**: on every `UserPromptSubmit` (automatic injection) and on `Stop` (session context save). Manually via `/honcho` subcommands.
+
+**What it does**: persistent cross-session memory via Honcho v3 self-hosted. On `UserPromptSubmit`, detects explicit memory triggers, saves any new memory first, then runs hybrid search in `Promise.all` — peer-scoped (explicit + inferred preferences, cross-project) and session-scoped (current project context). Merges by relevance, caps at `topN` items and ~2000 characters, injects the `[HONCHO MEMORY]...[/HONCHO MEMORY]` block via stdout. On `Stop`, saves the active feature/sprint context as `project-context`. Degrades gracefully when Honcho is unavailable.
+
+**Delegated agent**: runtime hooks, does not dispatch Task.
+
+**Output / artifacts**: `[HONCHO MEMORY]` block injected on every prompt; persistence in self-hosted Honcho.
+
+**Prerequisites**: Honcho v3 service available; `bun` installed to run `cli.js`.
+
+**When NOT to fire**: the skill is always on via hook — there is no "not firing". It can be disabled by removing the hook.
+
+### caveman
+
+Covered above in the **Style** section. Always on by project configuration, modulates compression by context. Can be turned off with "stop caveman".
+
+---
+
+## End-to-end pipeline
+
+Standard feature flow, from zero to deploy:
+
+```
+[opt-in]   grill-me        →  docs/discovery/DISCOVERY_<name>.md
+[opt-in]   to-prd          →  docs/prd/PRD_<name>.md
+[opt-in]   to-issues       →  docs/issues/ISSUES_<name>.md
+                                  │
+                                  ▼
+[auto]     project-manager →  analyst                  →  docs/plans/PLAN_<name>.md
+                              architect (if new ADR)   →  docs/decisions/ADR-NNN.md
+                              tech-lead (approves)
+                                  │
+                                  ▼
+[manual]   run-sprint  → sprint-runner
+                          ├── backend-developer    (parallel)
+                          ├── frontend-developer   (parallel)
+                          ├── database-engineer    (parallel)
+                          └── qa-engineer          (parallel)
+                                  │
+                                  ▼
+[auto]     auto-test-guard → gate-keeper (tests + senior+ gate)
+                                  │
+                                  ▼
+[auto]     api-integration-test (real smoke)
+                                  │
+                                  ▼
+[manual]   prd-ready-check → GO / NO-GO
+                                  │
+                                  ▼
+[auto]     brain-keeper → docs/brain/ (daily + feature + ADR + MOC)
+                                  │
+                                  ▼
+           commit + PR
+```
+
+Markers:
+
+- **[opt-in]**: the skill never auto-triggers. The user must ask explicitly.
+- **[auto]**: inside `run-sprint`, it is automatically triggered at the correct stage.
+- **[manual]**: user-driven, but can be chained by upstream skills.
+
+`caveman` and `honcho-memory` operate transversally across the entire pipeline.
+
+---
+
+## How to create a new skill
+
+Minimum structure:
+
+```
+.claude/skills/<slug>/
+└── SKILL.md
+```
+
+Required frontmatter:
+
+```yaml
+---
+name: <slug>
+description: |
+  One-line description of what the skill does, followed by a dense list
+  of EN and PT triggers. Cowork's classifier uses this field to decide
+  when to fire — the more real triggers, the better.
+  Triggers EN: "trigger one", "trigger two", "trigger three".
+  PT triggers: 'gatilho um', 'gatilho dois', 'gatilho três'.
+tools: Read, Glob, Grep, Write, Edit, Bash(command:*)
+model: sonnet
+---
+```
+
+Recommendations:
+
+1. **Description rich in PT + EN**. The classifier does keyword matching — without PT triggers, the skill will not fire for Portuguese-speaking users.
+2. **Inviolable block at the end of the file**: declare non-negotiable rules (e.g., "never run inline — always via `Task(subagent_type=...)`").
+3. **Restricted tools**: declare only the tools the skill really needs, especially for Bash (use `Bash(curl:*)` instead of `Bash`).
+4. **Model declaration**: Haiku for mechanical work, Sonnet for default, Opus only for irreversible decisions.
+5. **Stage → subagent mapping**: if the skill orchestrates multiple agents, declare the table in Markdown — this prevents Opus from running inline work that should be Sonnet/Haiku.
+6. **Invoke an agent via the Task tool**:
+
+   ```
+   Task(
+     subagent_type="backend-developer",
+     description="<3-5 words>",
+     prompt="""
+       Task: <description>
+       Acceptance criteria: <list>
+       Return: files created/modified + tests run.
+     """
+   )
+   ```
+
+7. **Register in `CLAUDE.md`** under "Skills (Cowork + Claude Code)" — table with name, triggers, output.
+8. **Update** `.claude/skills/README.md` with the new row.
+9. **Test** by firing via Cowork with a real user phrase.
+
+---
+
+## Cross-references
+
+- [Agents reference](agents-reference) — executor catalog with `model:` declared.
+- [Pipeline](pipeline) — end-to-end discovery → deploy flow with checkpoints and gates.
+- [Hooks reference](hooks-reference) — `UserPromptSubmit` and `Stop` used by `honcho-memory`.
+- [Quality gate](quality-gate) — senior+ gate thresholds validated by `auto-test-guard` and `prd-ready-check`.
+- [Autonomy matrix](autonomy-matrix) — who decides what and when to escalate to the human.
+- [Architecture overview](architecture-overview) — Skill + Agent layers and why commands were removed.