@eltonssouza/development-utility-kit 1.0.0

package/.claude/skills/brain-keeper/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: brain-keeper
+description: Use when completing a PLAN_* (end of run-sprint pipeline or close of run-sprint) to record development history in the Obsidian vault at docs/brain/. Triggers with "record in the brain", "update brain", "log of the day", "save ADR in vault", "close feature in brain", "record history", "update obsidian", "close sprint in vault". Creates daily/YYYY-MM-DD.md, features/<slug>.md, decisions/ADR-NNN-*.md (if new decision), bugs/<slug>.md (if fix), append in architecture/tech-debt.md (if debt accepted) and updates MOC. Provisions docs/brain/ + .obsidian/ with per-folder color snippet on first run. Idempotent WRITE-mode. DO NOT use for history questions (read vault directly) nor for trivial tasks. 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'.
+---
+
+# Brain Keeper — History Recording in the Obsidian Vault
+
+Skill that invokes the `brain-keeper` agent. Triggered upon completing each PLAN_*. Always reply in **American English**.
+
+---
+
+## When to trigger
+
+**Automatic**:
+- `run-sprint` Stage 7 (after PRD-ready GO).
+- `run-sprint` at sprint close (after `auto-test-guard` green gate).
+
+**Manual** (user says):
+- "record in the brain", "update brain", "log of the day"
+- "save ADR in vault", "close feature in brain"
+- "close sprint in vault", "record history"
+
+---
+
+## Prerequisites
+
+- A `PLAN_*.md` exists in `docs/plans/` for the completed work.
+- The sprint or task is finished (gate-keeper returned GREEN or the user confirmed done).
+- `docs/brain/` may or may not exist — the agent provisions it on first run.
+
+---
+
+## Do NOT use for
+
+- History questions — read the vault directly with Read/Grep tools.
+- Trivial tasks without a PLAN_*.
+- Manual edits of existing notes — the user edits; this skill only appends/creates.
+- Deleting or archiving vault notes — user decides manually.
+
+---
+
+## Dispatch
+
+```
+Task(
+  subagent_type: "brain-keeper",
+  description: "Record development history in the Obsidian vault at docs/brain/. Provision vault structure if missing. Create or update daily, feature, ADR, bug, tech-debt notes and MOC.",
+  prompt: "<full user message + plan path + sprint output summary>"
+)
+```
+
+---
+
+## Handoff
+
+The `brain-keeper` agent (`.claude/agents/brain-keeper.md`, model: sonnet) owns the complete execution contract:
+- Full provisioning flow for `docs/brain/` and `.obsidian/`.
+- Recording flow: daily, feature, ADR, bug, tech-debt, MOC.
+- Per-folder color table and graph.json configuration.
+- Idempotency and link-validation rules.

package/.claude/skills/brain-keeper/obsidian/app.json

@@ -0,0 +1,9 @@
+{
+  "alwaysUpdateLinks": true,
+  "newLinkFormat": "relative",
+  "useMarkdownLinks": false,
+  "attachmentFolderPath": "_attachments",
+  "newFileFolderPath": "daily",
+  "newFileLocation": "folder",
+  "showUnsupportedFiles": false
+}

package/.claude/skills/brain-keeper/obsidian/appearance.json

@@ -0,0 +1,4 @@
+{
+  "baseFontSize": 16,
+  "enabledCssSnippets": ["folder-colors"]
+}

package/.claude/skills/brain-keeper/obsidian/core-plugins.json

@@ -0,0 +1,20 @@
+[
+  "file-explorer",
+  "global-search",
+  "switcher",
+  "graph",
+  "backlink",
+  "outgoing-link",
+  "tag-pane",
+  "page-preview",
+  "daily-notes",
+  "templates",
+  "note-composer",
+  "command-palette",
+  "editor-status",
+  "starred",
+  "markdown-importer",
+  "outline",
+  "word-count",
+  "file-recovery"
+]

package/.claude/skills/brain-keeper/obsidian/daily-notes.json

@@ -0,0 +1,5 @@
+{
+  "folder": "daily",
+  "format": "YYYY-MM-DD",
+  "template": "_templates/daily"
+}

package/.claude/skills/brain-keeper/obsidian/graph.json

@@ -0,0 +1,32 @@
+{
+  "collapse-filter": true,
+  "search": "",
+  "showTags": false,
+  "showAttachments": false,
+  "hideUnresolved": false,
+  "showOrphans": true,
+  "collapse-color-groups": false,
+  "colorGroups": [
+    { "query": "path:_templates",   "color": { "a": 1, "rgb": 9741240 } },
+    { "query": "path:api",          "color": { "a": 1, "rgb": 3900150 } },
+    { "query": "path:architecture", "color": { "a": 1, "rgb": 11032055 } },
+    { "query": "path:bugs",         "color": { "a": 1, "rgb": 15680580 } },
+    { "query": "path:daily",        "color": { "a": 1, "rgb": 2278750 } },
+    { "query": "path:database",     "color": { "a": 1, "rgb": 16347926 } },
+    { "query": "path:decisions",    "color": { "a": 1, "rgb": 15381256 } },
+    { "query": "path:features",     "color": { "a": 1, "rgb": 440020 } },
+    { "query": "path:meetings",     "color": { "a": 1, "rgb": 15485081 } }
+  ],
+  "collapse-display": true,
+  "showArrow": false,
+  "textFadeMultiplier": 0,
+  "nodeSizeMultiplier": 1,
+  "lineSizeMultiplier": 1,
+  "collapse-forces": true,
+  "centerStrength": 0.518713248970312,
+  "repelStrength": 10,
+  "linkStrength": 1,
+  "linkDistance": 250,
+  "scale": 1,
+  "close": true
+}

package/.claude/skills/brain-keeper/obsidian/snippets/folder-colors.css

@@ -0,0 +1,90 @@
+/*
+ * folder-colors.css
+ * Cores por pasta no file explorer do Obsidian.
+ * Aplicado a:
+ *   - Título da pasta no nav lateral
+ *   - Arquivos dentro da pasta (cor mais clara/diluída)
+ *
+ * Editar paleta? Troque os valores hex abaixo.
+ */
+
+/* _templates — slate */
+.nav-folder-title[data-path="_templates"] .nav-folder-title-content,
+.nav-file-title[data-path^="_templates/"] .nav-file-title-content {
+  color: #94a3b8;
+}
+.nav-folder-title[data-path="_templates"]::before {
+  content: "🩶 ";
+}
+
+/* api — azul */
+.nav-folder-title[data-path="api"] .nav-folder-title-content,
+.nav-file-title[data-path^="api/"] .nav-file-title-content {
+  color: #3b82f6;
+}
+.nav-folder-title[data-path="api"]::before {
+  content: "🔵 ";
+}
+
+/* architecture — roxo */
+.nav-folder-title[data-path="architecture"] .nav-folder-title-content,
+.nav-file-title[data-path^="architecture/"] .nav-file-title-content {
+  color: #a855f7;
+}
+.nav-folder-title[data-path="architecture"]::before {
+  content: "🟣 ";
+}
+
+/* bugs — vermelho */
+.nav-folder-title[data-path="bugs"] .nav-folder-title-content,
+.nav-file-title[data-path^="bugs/"] .nav-file-title-content {
+  color: #ef4444;
+}
+.nav-folder-title[data-path="bugs"]::before {
+  content: "🔴 ";
+}
+
+/* daily — verde */
+.nav-folder-title[data-path="daily"] .nav-folder-title-content,
+.nav-file-title[data-path^="daily/"] .nav-file-title-content {
+  color: #22c55e;
+}
+.nav-folder-title[data-path="daily"]::before {
+  content: "🟢 ";
+}
+
+/* database — laranja */
+.nav-folder-title[data-path="database"] .nav-folder-title-content,
+.nav-file-title[data-path^="database/"] .nav-file-title-content {
+  color: #f97316;
+}
+.nav-folder-title[data-path="database"]::before {
+  content: "🟠 ";
+}
+
+/* decisions — amarelo */
+.nav-folder-title[data-path="decisions"] .nav-folder-title-content,
+.nav-file-title[data-path^="decisions/"] .nav-file-title-content {
+  color: #eab308;
+}
+.nav-folder-title[data-path="decisions"]::before {
+  content: "🟡 ";
+}
+
+/* features — ciano */
+.nav-folder-title[data-path="features"] .nav-folder-title-content,
+.nav-file-title[data-path^="features/"] .nav-file-title-content {
+  color: #06b6d4;
+}
+.nav-folder-title[data-path="features"]::before {
+  content: "🔷 ";
+}
+
+/* meetings — rosa */
+.nav-folder-title[data-path="meetings"] .nav-folder-title-content,
+.nav-file-title[data-path^="meetings/"] .nav-file-title-content {
+  color: #ec4899;
+}
+.nav-folder-title[data-path="meetings"]::before {
+  content: "🩷 ";
+}

package/.claude/skills/brain-keeper/obsidian/templates.json

@@ -0,0 +1,5 @@
+{
+  "folder": "_templates",
+  "dateFormat": "YYYY-MM-DD",
+  "timeFormat": "HH:mm"
+}

package/.claude/skills/brain-keeper/templates/README.md

@@ -0,0 +1,51 @@
+---
+title: Project Brain — MOC
+type: moc
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: [moc]
+---
+
+# 🧠 Project Brain
+
+Map of Content (MOC) — main index of the Obsidian vault. Updated automatically by `brain-keeper` upon completing each PLAN_*.
+
+## Structure
+
+```
+docs/brain/
+├── _templates/    🩶 templates (adr, feature, bug, daily, meeting)
+├── api/           🔵 REST contracts, endpoint changelog
+├── architecture/  🟣 system view, diagrams, tech-debt.md
+├── bugs/          🔴 postmortems
+├── daily/         🟢 daily log
+├── database/      🟠 model, migrations, schema
+├── decisions/     🟡 ADRs
+├── features/      🔷 notes per feature
+└── meetings/      🩷 minutes
+```
+
+## Recent decisions
+
+_Added by brain-keeper._
+
+## Active features
+
+_Added by brain-keeper._
+
+## Open / recent bugs
+
+_Added by brain-keeper._
+
+## Technical debt
+
+→ [[architecture/tech-debt]]
+
+## How to navigate
+
+- **Why did we decide X?** → [[decisions/]]
+- **How does Y work?** → [[features/]]
+- **What was done yesterday?** → [[daily/]]
+- **Did we have a bug with Z?** → [[bugs/]]
+- **What's the contract for endpoint E?** → [[api/]]
+- **How is table T modeled?** → [[database/]]

package/.claude/skills/brain-keeper/templates/adr.md

@@ -0,0 +1,40 @@
+---
+title: ADR-NNN — <short title>
+type: ADR
+status: Accepted
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: [decision]
+---
+
+# ADR-NNN: <short title>
+
+- **Status**: Proposed | Accepted | Superseded by ADR-XXX | Deprecated
+- **Date**: YYYY-MM-DD
+
+## Context
+
+_Why is this decision necessary? What problem or force is pushing toward a decision?_
+
+## Decision
+
+_What was decided, clearly and affirmatively._
+
+## Consequences
+
+**Gains:**
+- ...
+
+**Losses / costs:**
+- ...
+
+## Alternatives discarded
+
+- **Alternative A**: why it was rejected
+- **Alternative B**: why it was rejected
+
+## References
+
+- [[../daily/YYYY-MM-DD|Daily]]
+- [[../features/slug|Feature]]
+- Related commits / PRs

package/.claude/skills/brain-keeper/templates/bug.md

@@ -0,0 +1,35 @@
+---
+title: <short description>
+type: bug
+status: fixed
+severity: P0|P1|P2|P3
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: [bug]
+---
+
+# 🐛 <short description>
+
+## Symptom
+
+_How did the bug manifest? Error message, observed behavior, impact._
+
+## Root cause
+
+_Technical analysis. Don't confuse symptom with cause._
+
+## Fix applied
+
+_What was changed to resolve. Cite files/lines._
+
+## Prevention
+
+- New test: ...
+- Lint rule / review rule: ...
+- ADR: [[../decisions/ADR-NNN-slug|ADR-NNN]] (if applicable)
+
+## References
+
+- [[../daily/YYYY-MM-DD|Daily]]
+- [[../features/slug|Related feature]]
+- Commit / PR

package/.claude/skills/brain-keeper/templates/daily.md

@@ -0,0 +1,38 @@
+---
+title: YYYY-MM-DD — <day summary>
+type: daily
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: [daily]
+---
+
+# 📅 YYYY-MM-DD
+
+## Summary
+
+_1-2 lines about the main goal of the day._
+
+## Done
+
+- Feature: [[../features/slug|name]]
+- Fix: [[../bugs/slug|description]]
+- Refactor: ...
+
+## Decisions
+
+- [[../decisions/ADR-NNN-slug|ADR-NNN]] — title
+
+## Files
+
+**Created:** ...
+**Changed:** ...
+**Deleted:** ...
+
+## Blockers
+
+_What stalled progress? Waiting on whose decision? External dependency?_
+
+## Tomorrow
+
+- Next step 1
+- Next step 2

package/.claude/skills/brain-keeper/templates/feature.md

@@ -0,0 +1,62 @@
+---
+title: <feature name>
+type: feature
+status: in-progress
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+plan: docs/plans/PLAN_<NAME>.md
+tags: [feature]
+---
+
+# ✨ <feature name>
+
+## Goal
+
+_What business problem does this feature solve? What value is delivered?_
+
+## Requirements
+
+- [ ] FR: ...
+- [ ] NFR: ...
+- [ ] BR: ...
+- [ ] IR: ...
+
+## Decisions made
+
+- [[../decisions/ADR-NNN-slug|ADR-NNN]] — decision title
+- Minor decisions (without ADR) recorded here
+
+## Implementation
+
+### Backend
+
+- Endpoints: `GET /api/v1/...`, `POST /api/v1/...`
+- Entities: ...
+- Use cases: ...
+- Migrations: `V202X__description.sql`
+
+### Frontend
+
+- Routes: `/path`
+- Components: `FeatureListComponent`, `FeatureFormComponent`
+- Services: `FeatureService`
+
+## Tests
+
+- Backend (JUnit + Mockito + Testcontainers): N
+- Frontend (Jest + Testing Library): N
+- E2E (Playwright): N
+- Coverage: backend X% / frontend Y%
+
+## References
+
+- Plan: [[../../plans/PLAN_<NAME>|PLAN_<NAME>]]
+- Start daily: [[../daily/YYYY-MM-DD]]
+- Commits: ...
+- PR: ...
+
+## History
+
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD | Created |

package/.claude/skills/brain-keeper/templates/meeting.md

@@ -0,0 +1,34 @@
+---
+title: YYYY-MM-DD — <title>
+type: meeting
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: [meeting]
+---
+
+# 🗓️ <title>
+
+- **Date**: YYYY-MM-DD
+- **Attendees**: ...
+
+## Agenda
+
+1. ...
+2. ...
+
+## Discussion
+
+_Relevant points._
+
+## Decisions
+
+- [[../decisions/ADR-NNN-slug|ADR-NNN]] — title (if it became an ADR)
+- Minor decision: ...
+
+## Actions
+
+- [ ] @person — action — deadline
+
+## References
+
+- [[../daily/YYYY-MM-DD|Daily]]

package/.claude/skills/brain-keeper/templates/tech-debt.md

@@ -0,0 +1,21 @@
+---
+title: Technical debt
+type: tech-debt
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: [tech-debt, architecture]
+---
+
+# 🔧 Technical debt
+
+Items accepted as debt during development. Append by `brain-keeper` at the end of each PLAN_*.
+
+Severity:
+- **P0**: blocks production. Resolve before next release.
+- **P1**: high risk / impact. Next sprint.
+- **P2**: relevant but not urgent. Backlog next quarter.
+- **P3**: cosmetic / improvement. Long backlog.
+
+---
+
+## Items