arkaos 4.7.1 → 4.8.0

package/departments/content/skills/youtube-strategy/SKILL.md

@@ -1,9 +1,15 @@
 ---
 name: content/youtube-strategy
 description: >
-  YouTube strategy — channel positioning, title × thumbnail architecture,
-  hook + script structure, SEO + metadata, publishing cadence, cross-platform
-  distribution.
+  Full YouTube channel strategy in 7 deliverables: channel positioning, 10
+  title-thumbnail pairs, hook architecture, retention-mapped script
+  structure, SEO metadata stack, 90-day publishing cadence, and
+  cross-platform derivative spec. TRIGGER: "estratégia para o YouTube", "grow
+  my YouTube channel", "lançar canal de YouTube", "YouTube SEO", "CTR e
+  retenção", "/content youtube". SKIP: one video's packaging only ->
+  content/thumbnail-package; one video's script only ->
+  content/script-structure; Shorts-only content -> content/short-form
+  (vertical short-form, not channel strategy).
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/agent-design/SKILL.md

@@ -1,8 +1,15 @@
 ---
 name: dev/agent-design
 description: >
-  Design multi-agent architectures with role definitions, communication patterns,
-  tool schemas, guardrails, and evaluation frameworks.
+  Design multi-agent system architectures — supervisor/swarm/pipeline
+  patterns, agent role definitions, tool schemas, communication patterns,
+  guardrails, and memory design (Multi-Agent Architecture Patterns). TRIGGER:
+  "agent design", "desenha um sistema de agentes", "multi-agent architecture",
+  "arquitetura de agentes", "define agent roles", "/dev agent-design"; load
+  BEFORE building any agent system. SKIP: wiring an existing set of agents
+  into a flow with handoffs and failure policies -> dev/agent-workflow (it
+  designs the FLOW; this designs the AGENTS); non-agent system architecture ->
+  dev/architecture-design.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/agent-workflow/SKILL.md

@@ -1,8 +1,15 @@
 ---
 name: dev/agent-workflow
 description: >
-  Design production-grade multi-agent workflows with pattern selection,
-  handoff contracts, failure handling, and cost/context controls.
+  Design production-grade multi-agent workflows — pattern selection
+  (sequential, parallel, router, orchestrator, evaluator), handoff contracts,
+  validation gates, failure handling, and cost/context budgets (Workflow
+  Orchestration Patterns). TRIGGER: "agent workflow", "orquestra os agentes",
+  "workflow de agentes", "handoff between agents", "pipeline de subagents",
+  "/dev agent-workflow"; load BEFORE implementing orchestration code. SKIP:
+  defining the agents themselves (roles, tools, guardrails, memory) ->
+  dev/agent-design (it shapes the AGENTS; this wires the FLOW); one-off
+  complex task planning -> /arka-forge.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/ai-assisted-dev/SKILL.md

@@ -1,7 +1,13 @@
 ---
 name: dev/ai-assisted-dev
 description: >
-  AI-assisted development: prompt engineering for code, review AI output, TDD with AI.
+  AI-assisted development practice: prompt engineering for code generation,
+  structured review of AI output, and TDD with AI in the loop. TRIGGER: "ai
+  dev", "prompt engineering", "gera código com IA", "review AI output",
+  "programar com IA", "code with AI", "/dev ai-dev". SKIP: securing AI/LLM
+  systems (prompt injection, guardrails) -> dev/ai-security (assessment, not
+  development practice); building MCP servers -> dev/mcp-builder; plain TDD
+  without AI in the loop -> dev/tdd-cycle.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/ai-security/SKILL.md

@@ -1,8 +1,15 @@
 ---
 name: dev/ai-security
 description: >
-  AI/ML-specific security assessment: prompt injection, model poisoning,
-  data leakage, agent tool abuse, and MITRE ATLAS technique mapping.
+  AI/ML-specific security assessment with OWASP ML Top 10, NIST AI RMF, and
+  MITRE ATLAS technique mapping: prompt injection, jailbreaks, model
+  poisoning, data leakage, agent tool abuse, and guardrail design. TRIGGER:
+  "ai security", "prompt injection", "segurança do modelo", "jailbreak",
+  "guardrails", "audita o agente", "/dev ai-security". SKIP: general
+  application security (OWASP Top 10, headers, dependencies) ->
+  dev/security-audit (web/app scope, not models); vetting a third-party skill
+  before install -> dev/skill-audit; offensive engagement planning ->
+  dev/red-team.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/api-design/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: dev/api-design
 description: >
-  Design REST or GraphQL APIs with versioning, documentation, and contracts.
-  Follows OpenAPI spec for REST, SDL for GraphQL.
+  Design REST or GraphQL APIs with resource modeling, versioning, pagination,
+  error contracts, and documentation — OpenAPI 3 spec for REST, SDL for
+  GraphQL, Laravel conventions included. TRIGGER: "api design", "desenha a
+  API", "endpoints", "contrato da API", "REST", "GraphQL", "/dev api-design";
+  load BEFORE implementing controllers or routes. SKIP: system architecture
+  beyond the API surface -> dev/architecture-design; the database schema
+  behind the API -> dev/db-schema; requirements not yet defined -> dev/spec
+  first.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/app-test/SKILL.md

@@ -1,9 +1,13 @@
 ---
 name: dev/app-test
 description: >
-  Build, launch, and click through a native app (macOS or iOS Simulator).
-  Screenshot each screen, report crashes or visual issues.
-  Requires Computer Use (/mcp → computer-use).
+  Build, launch, and click through a native app (macOS or iOS Simulator) via
+  Computer Use — exercises every control systematically, screenshots each
+  screen, reports crashes and visual issues. TRIGGER: "app test", "testa a app
+  nativa", "test the macOS app", "iOS simulator", "clica pela app toda", "/dev
+  app-test"; requires Computer Use (/mcp -> computer-use). SKIP: web app flows
+  in a browser -> dev/demo-gif (browser recording, not native apps); writing
+  automated unit/feature tests -> dev/tdd-cycle.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/architecture-design/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: dev/architecture-design
 description: >
-  Design system architecture using Clean Architecture, Hexagonal, or DDD patterns.
-  Produces an ADR (Architecture Decision Record) saved to Obsidian.
+  Design system architecture with Clean Architecture, Hexagonal, or DDD
+  patterns and produce an ADR (Architecture Decision Record) saved to
+  Obsidian, approved by Marco (CTO). TRIGGER: "architecture", "arquitetura do
+  sistema", "ADR", "system design", "desenha a arquitetura", "clean
+  architecture", "/dev architecture"; load BEFORE large structural changes.
+  SKIP: deep domain modeling (bounded contexts, aggregates, events) ->
+  dev/ddd-model (strategic DDD detail); API contract design only ->
+  dev/api-design; feature requirements -> dev/spec.
 allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, WebFetch]
 ---
 

package/departments/dev/skills/changelog/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/changelog
 description: >
-  Generate changelogs from git history using conventional commits. Lint commit messages, detect version bumps, and render Keep a Changelog format.
+  Generate changelogs from git history using Conventional Commits: lints
+  commit messages, detects the SemVer bump (MAJOR/MINOR/PATCH), groups
+  entries, and renders Keep a Changelog format. TRIGGER: "changelog", "gera o
+  changelog", "release notes", "notas de versão", "what changed since the last
+  tag", "/dev changelog". SKIP: planning and executing the whole release
+  (readiness checklist, deploy sequence, rollback) -> dev/release (the
+  changelog is one artifact of it); shipping the deployment itself ->
+  dev/deploy.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/ci-cd-pipeline/SKILL.md

@@ -1,8 +1,13 @@
 ---
 name: dev/ci-cd-pipeline
 description: >
-  Design and generate CI/CD pipelines from detected project stack.
-  GitHub Actions and GitLab CI with caching, matrix builds, and deployment gates.
+  Design and generate CI/CD pipelines from the detected project stack — GitHub
+  Actions or GitLab CI with lint/test/build/deploy stages, dependency caching,
+  matrix builds, and gated production deploys. TRIGGER: "ci/cd", "pipeline",
+  "github actions", "cria o pipeline", "gitlab ci", "automatiza os testes no
+  CI", "/dev ci-cd-pipeline". SKIP: deployment strategy design (blue-green,
+  canary, GitOps, monitoring) -> dev/devops-pipeline (strategy; this generates
+  the config); executing a deploy right now -> dev/deploy.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/codebase-onboard/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/codebase-onboard
 description: >
-  Analyze an existing codebase and generate onboarding documentation: architecture, patterns, setup, key files.
+  Analyze an existing codebase and generate onboarding documentation for new
+  developers: stack detection, architecture map, patterns, setup instructions,
+  and key files, tuned to the audience (junior/senior/contractor). TRIGGER:
+  "onboarding docs", "explica este codebase", "how does this repo work",
+  "documenta a arquitetura para novos devs", "/dev codebase-onboard". SKIP:
+  registering a project into ARKA OS (PROJECT.md, MCPs, Obsidian pages) ->
+  dev/onboard (system registration, not human docs); general README/API doc
+  updates -> dev/docs.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/db-design/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/db-design
 description: >
-  Database design: schema, normalization, indexes, RLS policies, migration planning.
+  Database design with the DBA (Vasco): schema modeling, normalization, index
+  strategy, RLS policies, and migration planning — outputs ERD, migration
+  scripts, and policy definitions. TRIGGER: "database design", "desenha a base
+  de dados", "modelo de dados", "indexes", "RLS", "planeia as migrações",
+  "/dev db"; load BEFORE writing migrations. SKIP: feature-level schema with
+  Laravel migration code and cross-cutting concerns -> dev/db-schema (feature
+  scope; this is DB-wide design); slow-query diagnosis ->
+  dev/performance-audit.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/db-schema/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: dev/db-schema
 description: >
-  Design database schemas with normalization, indexing, migrations,
-  RLS policies, ERD generation, and cross-cutting concerns.
+  Design a feature's database schema: normalization to 3NF, relationship
+  mapping, cross-cutting concerns (timestamps, soft deletes, multi-tenancy,
+  audit trail, optimistic locking), index strategy, Laravel migration code,
+  and Mermaid ERD. TRIGGER: "db schema", "tabelas para esta feature", "cria a
+  migração", "schema design", "modelo relacional", "/dev db-schema"; load
+  BEFORE writing migration files. SKIP: database-wide design, RLS planning, or
+  DBA-level work -> dev/db-design (Vasco's DB-wide scope; this is
+  feature-level); query performance tuning -> dev/performance-profiler.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/ddd-model/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/ddd-model
 description: >
-  Domain-Driven Design modeling: bounded contexts, aggregates, domain events, context mapping, ubiquitous language.
+  Domain-Driven Design modeling with the Evans/Vernon playbook: bounded
+  contexts, aggregates, domain events, context mapping, and ubiquitous
+  language — outputs a DDD model with context map and domain event catalog.
+  TRIGGER: "DDD", "domain model", "bounded context", "modela o domínio",
+  "aggregates", "linguagem ubíqua", "/dev ddd". SKIP: overall system
+  architecture and ADRs -> dev/architecture-design (strategic DDD is one
+  option there; this goes deeper); persisting the model as tables and
+  migrations -> dev/db-schema.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/demo-gif/SKILL.md

@@ -1,9 +1,13 @@
 ---
 name: dev/demo-gif
 description: >
-  Record a GIF demo of a user flow in the browser. Navigates to a URL,
-  executes described interactions, and saves the recording as a GIF file.
-  Requires browser integration (claude --chrome or /chrome).
+  Record a GIF demo of a browser user flow: navigates to a URL, executes the
+  described interactions (click, type, scroll) with visual pauses, and saves
+  the recording as a GIF for demos, docs, or bug reports. TRIGGER: "demo gif",
+  "grava um gif", "record the flow", "gravação do fluxo", "gif para o bug
+  report", "/dev demo-gif"; requires browser integration (claude --chrome or
+  /chrome). SKIP: native macOS/iOS app walkthroughs -> dev/app-test (Computer
+  Use, not browser); writing the docs around the demo -> dev/docs.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/dependency-audit/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/dependency-audit
 description: >
-  Audit project dependencies for vulnerabilities, license compliance, outdated packages, and supply chain risks.
+  Audit project dependencies across ecosystems (npm, Composer, pip, Go, Cargo)
+  for known CVEs, license compliance (GPL/AGPL risk), outdated packages,
+  unused packages, and supply chain risks like typosquatting. TRIGGER:
+  "dependency audit", "audita as dependências", "npm audit", "vulnerabilidades
+  nos packages", "licenças das libs", "outdated packages", "/dev
+  dependency-audit". SKIP: full application security review (OWASP Top 10,
+  headers, injection) -> dev/security-audit (dependencies are one section
+  there); whole-stack version and upgrade-path review -> dev/stack-check.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/deploy/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/deploy
 description: >
-  Deploy to environment: pre-deploy checks, deployment execution, post-deploy verification.
+  Deploy to an environment with blue-green/canary strategy: pre-deploy checks,
+  deployment execution, and post-deploy verification — outputs a deployment
+  report with status, rollback plan, and monitoring links. TRIGGER: "deploy",
+  "faz deploy", "ship to staging", "manda para produção", "release to prod",
+  "/dev deploy". SKIP: designing the pipeline that automates deploys ->
+  dev/ci-cd-pipeline (config generation, not execution); coordinating the
+  whole release (versioning, freeze, sign-offs) -> dev/release; production
+  failure during rollout -> dev/incident.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/devops-pipeline/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/devops-pipeline
 description: >
-  CI/CD pipeline design: build, test, deploy stages with blue-green/canary strategies.
+  CI/CD pipeline design following the Three Ways (Gene Kim) and GitOps: build,
+  test, deploy stages with blue-green/canary strategies — outputs pipeline
+  config, deployment strategy, and monitoring setup. TRIGGER: "devops
+  pipeline", "estratégia de deployment", "gitops", "blue-green", "canary",
+  "desenha o pipeline", "/dev pipeline". SKIP: quickly generating
+  stack-detected GitHub Actions/GitLab CI YAML -> dev/ci-cd-pipeline (the
+  generator; this designs the strategy); executing a deploy right now ->
+  dev/deploy.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/docs/SKILL.md

@@ -1,7 +1,13 @@
 ---
 name: dev/docs
 description: >
-  Generate or update project documentation: README, API docs, architecture docs.
+  Generate or update project documentation — README, API docs, and
+  architecture docs — saved to the project and Obsidian. TRIGGER: "docs",
+  "documentação", "atualiza o README", "write the docs", "documenta a API",
+  "/dev docs". SKIP: onboarding documentation for new developers on an
+  existing codebase -> dev/codebase-onboard (audience-tuned onboarding, not
+  general docs); changelog and release notes from git history ->
+  dev/changelog; operational procedures for on-call -> dev/runbook.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/env-secrets/SKILL.md

@@ -1,7 +1,13 @@
 ---
 name: dev/env-secrets
 description: >
-  Audit .env files for leaked secrets, validate .env.example sync, and guide vault integration.
+  Audit environment files and source for leaked secrets (OWASP Secrets
+  Management): .gitignore coverage, hardcoded keys, .env/.env.example drift,
+  git history scans (GitLeaks, detect-secrets), vault integration guidance,
+  and emergency rotation. TRIGGER: "secrets", "env audit", "chave exposta",
+  "leaked API key", "segredos no git", "verifica o .env", "/dev env-secrets".
+  SKIP: full OWASP application audit -> dev/security-audit (secrets are one
+  check there); ISO 27001/ISMS evidence work -> dev/security-compliance.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/incident/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/incident
 description: >
-  Incident response framework: severity classification, timeline reconstruction, runbook execution, stakeholder communication, and post-incident review.
+  Incident response with Google SRE incident management: severity
+  classification (SEV1-4), incident commander checklist, war room setup,
+  mitigation (rollback vs fix-forward), stakeholder communication templates,
+  and blameless post-incident review. TRIGGER: "incident", "produção em
+  baixo", "outage", "site is down", "SEV1", "estamos com um incidente", "/dev
+  incident"; load IMMEDIATELY when production breaks. SKIP: writing the
+  procedures before anything breaks -> dev/runbook (preparation, not
+  response); planned rollback as part of a release -> dev/release.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/mcp/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: arka-dev-mcp
 description: >
-  MCP (Model Context Protocol) management for projects. Apply pre-configured MCP profiles,
-  add or remove individual MCP servers, list all available MCPs from the registry, and check
-  which MCPs are active in a project. Generates .mcp.json and .claude/settings.local.json.
-  Use when user says "mcp", "apply mcp", "add mcp", "mcp status", "mcp list", "remove mcp",
-  "model context protocol", "mcp profile", or wants to configure Claude Code integrations.
+  MCP (Model Context Protocol) management for projects: apply pre-configured
+  MCP profiles (laravel, nuxt, ecommerce, full-stack...), add or remove
+  individual servers, list the registry, check project status — generates
+  .mcp.json and .claude/settings.local.json. TRIGGER: "mcp", "apply mcp",
+  "adiciona um mcp", "mcp status", "configura os MCPs", "model context
+  protocol", "/dev mcp". SKIP: building a NEW MCP server from an API contract
+  -> dev/mcp-builder (creation, not configuration); onboarding a whole project
+  (MCP profile included) -> dev/onboard.
 ---
 
 <!-- arka:kb-first-prefix begin -->

package/departments/dev/skills/mcp-builder/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: dev/mcp-builder
 description: >
-  Build production-ready MCP servers from API contracts. Scaffold from OpenAPI,
-  validate tool manifests, design auth and versioning strategies.
+  Build production-ready MCP servers from API contracts: scaffold from OpenAPI
+  specs, generate typed tool manifests, design auth/safety/versioning
+  strategies, and validate in strict mode before publishing (Python or
+  TypeScript runtimes). TRIGGER: "mcp builder", "cria um servidor MCP", "build
+  MCP server", "expose my API as tools", "converte OpenAPI em MCP", "/dev
+  mcp-builder". SKIP: applying or managing existing MCP servers in a project
+  (.mcp.json, profiles) -> dev/mcp (configuration, not creation); designing
+  the underlying API itself -> dev/api-design.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/observability/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/observability
 description: >
-  Design observability strategies: SLI/SLO frameworks, golden signals, structured logging, distributed tracing, alerting, and dashboards.
+  Design observability strategies with Google SRE practice: SLI/SLO frameworks
+  with error budgets, golden signals (latency, traffic, errors, saturation),
+  structured logging standards, distributed tracing, burn-rate alerting, and
+  dashboard hierarchy. TRIGGER: "observability", "monitoring", "SLO",
+  "alertas", "métricas do serviço", "logging estruturado", "tracing", "/dev
+  observability". SKIP: responding to a live incident -> dev/incident
+  (observability is preparation); measuring and fixing a specific performance
+  bottleneck -> dev/performance-profiler.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/onboard/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: arka-dev-onboard
 description: >
-  Onboard existing projects into ARKA OS with automatic stack detection, codebase analysis,
-  MCP configuration, and Obsidian documentation. Analyzes composer.json, package.json,
-  .env files, directory structure to auto-detect framework, database, auth, payments, and
-  architecture patterns. Generates PROJECT.md, applies MCP profiles, creates Obsidian project
-  pages, and registers in ARKA OS — making any existing codebase "ready to work" with full
-  context. Also manages project ecosystems (groups of related projects like API + frontend).
-  Use when user says "onboard", "register project", "add project", "import project",
-  "existing project", "ecosystem", or wants to bring an existing codebase into ARKA OS.
+  Onboard EXISTING projects into ARKA OS: auto-detects stack from
+  composer.json/package.json/.env, analyzes architecture and git, applies MCP
+  profiles, generates PROJECT.md and Obsidian pages, and manages ecosystems
+  (groups of related projects like API + frontend). TRIGGER: "onboard",
+  "regista o projeto", "add project", "import project", "ecosystem", "traz
+  este projeto para o ArkaOS", "/dev onboard". SKIP: creating a NEW project
+  from a template -> dev/scaffold (greenfield, not existing code);
+  human-readable onboarding docs for developers -> dev/codebase-onboard.
 ---
 
 # Project Onboarding — ARKA OS Dev Department

package/departments/dev/skills/performance-audit/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: dev/performance-audit
 description: >
-  Performance audit covering Core Web Vitals, API latency, database queries,
-  and caching strategy. Targets and budgets based on Google/industry standards.
+  Performance audit against Google/industry budgets: Core Web Vitals (LCP,
+  INP, CLS), API latency percentiles, database query analysis (EXPLAIN
+  ANALYZE, N+1, indexes), caching strategy, and infrastructure (CDN,
+  compression) — outputs prioritized fixes. TRIGGER: "performance audit", "o
+  site está lento", "core web vitals", "lighthouse", "API lenta", "queries
+  lentas", "/dev performance". SKIP: iterative measure-fix-remeasure work on
+  one bottleneck -> dev/performance-profiler (deep-dive; this is the broad
+  audit); SLO and alerting design -> dev/observability.
 allowed-tools: [Read, Bash, Grep, Glob, Agent, WebFetch]
 ---
 

package/departments/dev/skills/performance-profiler/SKILL.md

@@ -1,8 +1,15 @@
 ---
 name: dev/performance-profiler
 description: >
-  Performance profiling with bottleneck identification, before/after measurement,
-  optimization checklists, and load testing guidance.
+  Performance profiling with measure-first discipline: establish a baseline
+  (P50/P95/P99, RPS, memory), identify the bottleneck via flamegraphs,
+  slow-query logs, or heap snapshots, apply one fix at a time, and prove the
+  delta with before/after numbers; includes load testing guidance. TRIGGER:
+  "profile", "profiling", "bottleneck", "porque é que isto está lento",
+  "flamegraph", "mede o antes e depois", "/dev performance-profiler". SKIP:
+  broad health check across frontend/API/DB/caching -> dev/performance-audit
+  (the audit is wide, the profiler is deep); monitoring/SLO design ->
+  dev/observability.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/rag-architect/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: dev/rag-architect
 description: >
-  Design RAG pipelines with chunking strategies, embedding selection,
-  retrieval optimization, and evaluation frameworks.
+  Design RAG pipelines end-to-end: chunking strategies, embedding model
+  selection, vector database comparison (Pinecone, Qdrant, pgvector...),
+  hybrid retrieval with reranking, query transformation (HyDE, multi-query),
+  and evaluation frameworks. TRIGGER: "RAG", "retrieval augmented generation",
+  "vector database", "chunking", "embeddings", "pesquisa semântica sobre os
+  meus documentos", "/dev rag-architect". SKIP: multi-agent system design
+  around the RAG -> dev/agent-design; securing the pipeline against injection
+  via retrieved content -> dev/ai-security.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/red-team/SKILL.md

@@ -1,7 +1,16 @@
 ---
 name: dev/red-team
 description: >
-  Offensive security engagement planning: MITRE ATT&CK kill-chain, technique scoring, attack path analysis, OPSEC assessment.
+  Offensive security engagement planning with MITRE ATT&CK and the Cyber Kill
+  Chain: technique scoring, attack path analysis, OPSEC assessment, and crown
+  jewel targeting — requires signed Rules of Engagement. TRIGGER: "red team",
+  "adversary simulation", "simula um ataque", "attack path", "kill chain",
+  "planeia o pentest", "/dev red-team". SKIP: adversarially breaking a
+  specific code diff or design (abuse cases, not a campaign) ->
+  dev/adversarial-review (reviews an artifact, not an engagement); defensive
+  code/config audit (OWASP Top 10) -> dev/security-audit (defense, not
+  offense); AI/LLM attack surface -> dev/ai-security; certification evidence
+  -> dev/security-compliance.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/refactor-plan/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/refactor-plan
 description: >
-  Plan a refactoring: identify code smells, select refactoring patterns, ensure test safety net.
+  Plan a refactoring with Martin Fowler's catalog: identify code smells,
+  select refactoring patterns, assess risk, and ensure a test safety net
+  before touching code. TRIGGER: "refactor", "refatora isto", "limpa este
+  código", "code smells", "melhora a estrutura", "clean up this module", "/dev
+  refactor"; load BEFORE restructuring existing code. SKIP: reviewing a diff
+  or PR for quality -> dev/clean-code-review (a verdict on code, not a
+  restructuring plan); systemic debt inventory and prioritization ->
+  dev/tech-debt; new feature work -> dev/spec first.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/release/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/release
 description: >
-  Release planning and execution: versioning strategy, readiness checklists, deployment coordination, rollback procedures, and hotfix management.
+  Release planning and execution with SemVer and DORA practice: version bump
+  detection from conventional commits, readiness checklists (CI, coverage,
+  audits, approvals), deployment sequencing with code freeze, rollback
+  triggers, and hotfix management. TRIGGER: "release", "faz o release", "ship
+  version", "lança a versão", "prepara a release", "hotfix", "/dev release".
+  SKIP: only generating the changelog -> dev/changelog (one artifact of the
+  release); executing the deployment step itself -> dev/deploy; live failure
+  during rollout -> dev/incident.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/runbook/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/runbook
 description: >
-  Generate operational runbooks for deployment, incident response, rollback, and scaling procedures.
+  Generate operational runbooks from service analysis (Google SRE): service
+  overview, health checks, step-by-step deployment with verification, rollback
+  procedures, incident response contacts, and scaling triggers — every command
+  copy-pasteable and staging-tested. TRIGGER: "runbook", "procedimento
+  operacional", "how do we deploy this service", "documenta o rollback",
+  "on-call docs", "/dev runbook". SKIP: responding to a live incident ->
+  dev/incident (runbooks are written BEFORE the fire); general project
+  documentation -> dev/docs.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 

package/departments/dev/skills/scaffold/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: arka-dev-scaffold
 description: >
-  Project scaffolding from real git repositories. Creates new Laravel, Nuxt, Vue, React, or
-  Next.js projects with automated dependency installation, mandatory packages, MCP configuration,
-  Laravel Herd linking, Obsidian project pages, and initial git commit. Full-stack monorepo support.
-  Use when user says "scaffold", "new project", "create project", "start project", "bootstrap",
-  "init project", "setup project", or wants to create a new codebase from a template.
+  Project scaffolding from real git starter repos: creates NEW Laravel, Nuxt,
+  Vue, React, or Next.js projects with dependency installation, mandatory
+  packages, MCP configuration, Laravel Herd linking, Obsidian pages, and
+  initial commit; full-stack monorepo support. TRIGGER: "scaffold", "new
+  project", "cria um projeto novo", "bootstrap", "começa um projeto Laravel",
+  "setup project", "/dev scaffold". SKIP: bringing an EXISTING codebase into
+  ARKA OS -> dev/onboard (analysis and registration, not creation); only
+  adding MCPs to a current project -> dev/mcp.
 ---
 
 # Project Scaffolding — ARKA OS Dev Department

package/departments/dev/skills/security-audit/SKILL.md

@@ -1,7 +1,15 @@
 ---
 name: dev/security-audit
 description: >
-  OWASP Top 10 (2025) security audit with dependency scanning and security headers check.
+  OWASP Top 10 (2025) security audit: access control, cryptographic failures,
+  injection, misconfiguration, plus dependency scanning (npm/composer/pip
+  audit), secrets detection, and security headers — outputs a severity-ranked
+  report with a block/release recommendation. TRIGGER: "security audit",
+  "audita a segurança", "is this secure", "vulnerabilidades", "OWASP", "revê a
+  segurança antes do release", "/dev security-audit". SKIP: AI/LLM-specific
+  threats (prompt injection, model abuse) -> dev/ai-security; deep
+  dependency/license analysis -> dev/dependency-audit; ISO 27001 certification
+  prep -> dev/security-compliance.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---