arkaos 4.7.0 → 4.8.0

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
@@ -14,17 +17,21 @@ Create new projects from real git repositories with full automation: dependencie
 
 ## Commands
 
-| Command | Git Repository | Stack |
-|---------|---------------|-------|
-| `/dev scaffold laravel <name>` | `https://${GIT_HOST}/laravel/laravel.git` (override with `ARKAOS_LARAVEL_STARTER_REPO` env) | Laravel + Herd |
-| `/dev scaffold nuxt-saas <name>` | `https://github.com/nuxt-ui-templates/dashboard.git` | Nuxt 3 Dashboard |
-| `/dev scaffold nuxt-landing <name>` | `https://github.com/nuxt-ui-templates/landing.git` | Nuxt 3 Landing |
-| `/dev scaffold nuxt-docs <name>` | `https://github.com/nuxt-ui-templates/docs.git` | Nuxt 3 Docs |
-| `/dev scaffold vue-saas <name>` | `https://github.com/nuxt-ui-templates/dashboard-vue.git` | Vue 3 Dashboard |
-| `/dev scaffold vue-landing <name>` | `https://github.com/nuxt-ui-templates/starter-vue.git` | Vue 3 Landing |
-| `/dev scaffold full-stack <name>` | Laravel + Nuxt (both repos) | Full-stack |
-| `/dev scaffold react <name>` | React starter (TBD) | React SPA |
-| `/dev scaffold nextjs <name>` | Next.js starter (TBD) | Next.js App |
+<!-- Column convention: command | DESCRIPTION | repo. The registry
+     generator (bin/arka-registry-gen) reads column 2 as the user-facing
+     description — a repo URL there ships garbled command help (QG
+     blocker, 2026-07-09). -->
+| Command | Description | Git Repository |
+|---------|-------------|----------------|
+| `/dev scaffold laravel <name>` | Scaffold a Laravel app into ~/Herd from the starter repo | `https://${GIT_HOST}/laravel/laravel.git` (override with `ARKAOS_LARAVEL_STARTER_REPO` env) |
+| `/dev scaffold nuxt-saas <name>` | Scaffold a Nuxt 3 SaaS dashboard into ~/Work | `https://github.com/nuxt-ui-templates/dashboard.git` |
+| `/dev scaffold nuxt-landing <name>` | Scaffold a Nuxt 3 landing page into ~/Work | `https://github.com/nuxt-ui-templates/landing.git` |
+| `/dev scaffold nuxt-docs <name>` | Scaffold a Nuxt 3 docs site into ~/Work | `https://github.com/nuxt-ui-templates/docs.git` |
+| `/dev scaffold vue-saas <name>` | Scaffold a Vue 3 SaaS dashboard into ~/Work | `https://github.com/nuxt-ui-templates/dashboard-vue.git` |
+| `/dev scaffold vue-landing <name>` | Scaffold a Vue 3 landing page into ~/Work | `https://github.com/nuxt-ui-templates/starter-vue.git` |
+| `/dev scaffold full-stack <name>` | Scaffold Laravel (~/Herd) + Nuxt (~/Work) as a linked pair | Laravel + Nuxt starter repos above |
+| `/dev scaffold react <name>` | Scaffold a React SPA — starter repo not yet selected | (not yet selected) |
+| `/dev scaffold nextjs <name>` | Scaffold a Next.js app — starter repo not yet selected | (not yet selected) |
 
 ## Workflow: /dev scaffold <type> <name>
 

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]
 ---
 

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

@@ -1,7 +1,14 @@
 ---
 name: dev/security-compliance
 description: >
-  Security audit preparation, ISMS gap analysis, control assessment, and ISO 27001 certification support for engineering teams.
+  Security audit preparation and ISO 27001 certification support: ISMS gap
+  analysis against clauses 4-10, Annex A control assessment (93 controls),
+  maturity scoring, evidence collection, and finding classification
+  (major/minor NC). TRIGGER: "compliance", "ISO 27001", "ISMS", "auditoria de
+  certificação", "gap analysis de segurança", "audit readiness", "/dev
+  security-compliance". SKIP: hands-on technical vulnerability audit ->
+  dev/security-audit (code and config, not the management system); SOC 2 or
+  GDPR programmes -> ops skills arka-soc2-compliance / arka-gdpr-compliance.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

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

@@ -1,7 +1,15 @@
 ---
 name: dev/skill-audit
 description: >
-  Audit AI agent skills for security vulnerabilities: prompt injection, code execution, data leakage, supply chain risks.
+  Audit AI agent skill directories for security risks BEFORE installation
+  (OWASP LLM Top 10): code execution patterns (eval, shell injection,
+  exfiltration), prompt injection in SKILL.md, supply chain risks
+  (typosquatting, unpinned deps), and filesystem violations — PASS/WARN/FAIL
+  verdict. TRIGGER: "skill audit", "audita esta skill", "is this skill safe",
+  "verifica a skill antes de instalar", "scan the skill", "/dev skill-audit".
+  SKIP: securing your own AI application or agents -> dev/ai-security (your
+  system, not third-party skills); project dependency CVEs ->
+  dev/dependency-audit.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

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

@@ -1,20 +1,17 @@
 ---
 name: arka-dev-spec
 description: >
-  Spec-driven development gate, constitution MUST rule spec-driven (Constitution #7 — no code
-  without an approved spec): creates, validates, and manages feature
-  specifications with the Living Specs engine (core/specs/), covering scope,
-  acceptance criteria, data model, API contracts, UI/UX requirements, edge
-  cases, and test scenarios. TRIGGER: "spec", "specification",
-  "requirements", "requisitos", "define feature", "write spec", "escreve a
-  spec", "critérios de aceitação", "describe what to build", "/dev spec";
-  auto-invoked as Phase 0 of every code-modifying dev workflow (/dev
-  feature, /dev api, /dev db, code-modifying /dev do) — load BEFORE writing
-  any code. SKIP: multi-agent planning, complexity escalation, or "how do
-  we execute this" -> /arka-forge (the Forge plans the WORK; spec defines
-  the WHAT — requirements and acceptance criteria); reviewing existing code
-  -> dev/code-review; /dev debug and /dev refactor operate on existing code
-  and need no new spec.
+  Spec-driven development gate, constitution MUST rule spec-driven
+  (Constitution #7 — no code without an approved spec): creates, validates,
+  and manages feature specifications with the Living Specs engine
+  (core/specs/) — scope, acceptance criteria, data model, API contracts,
+  edge cases, test scenarios. TRIGGER: "spec", "requirements", "requisitos",
+  "write spec", "escreve a spec", "critérios de aceitação", "/dev spec";
+  auto-invoked as Phase 0 of every code-modifying dev workflow — load BEFORE
+  writing any code. SKIP: multi-agent planning or "how do we execute this"
+  -> /arka-forge (the Forge plans the WORK; spec defines the WHAT);
+  reviewing existing code -> dev/code-review; /dev debug and /dev refactor
+  operate on existing code and need no new spec.
 ---
 
 # Spec-Driven Development — ARKA OS Dev Department

package/departments/dev/skills/stack-check/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/stack-check
 description: >
-  Audit current tech stack: versions, dependencies, security, performance, upgrade paths.
+  Audit the current tech stack through a 12-Factor lens: framework and runtime
+  versions, dependency health, security posture, performance, and upgrade
+  paths — outputs a stack health report with upgrade recommendations and risk
+  assessment. TRIGGER: "stack check", "audita o stack", "are we outdated",
+  "devíamos atualizar o Laravel", "upgrade path", "tech stack review", "/dev
+  stack-check". SKIP: CVE/license-focused package analysis ->
+  dev/dependency-audit (deps only; stack-check is holistic); accumulated code
+  debt scoring -> dev/tech-debt.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/dev/skills/tdd-cycle/SKILL.md

@@ -1,8 +1,14 @@
 ---
 name: dev/tdd-cycle
 description: >
-  Test-Driven Development using Kent Beck's Red-Green-Refactor cycle.
-  Write failing test first, minimal code to pass, then refactor.
+  Test-Driven Development with Kent Beck's Red-Green-Refactor cycle: write the
+  failing test first, minimum code to pass, refactor on green — enforces the
+  testing pyramid (70/20/10) and >= 80% coverage across
+  PHPUnit/Pest/Vitest/Jest/pytest/Playwright. TRIGGER: "test", "TDD", "escreve
+  os testes", "write tests first", "cobertura de testes", "red green
+  refactor", "/dev test"; load BEFORE implementing feature code. SKIP:
+  clicking through a native app -> dev/app-test (exploratory, not automated
+  tests); planning a refactor's safety net -> dev/refactor-plan.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
 ---
 

package/departments/dev/skills/tech-debt/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: dev/tech-debt
 description: >
-  Identify, classify, score, and prioritize technical debt. Generate remediation plans with cost-of-delay analysis.
+  Identify, classify, score, and prioritize technical debt (Ward Cunningham
+  metaphor + cost-of-delay): six debt categories, weighted severity scoring, a
+  prioritization matrix, and remediation plans tied to velocity and risk.
+  TRIGGER: "tech debt", "dívida técnica", "o código está uma confusão",
+  "prioritize cleanup", "TODOs everywhere", "/dev tech-debt". SKIP: planning
+  one specific refactoring with a test safety net -> dev/refactor-plan (the
+  execution plan; tech-debt is the inventory); dependency staleness only ->
+  dev/dependency-audit.
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 

package/departments/ecom/skills/analytics/SKILL.md

@@ -1,7 +1,15 @@
 ---
 name: ecom/analytics
 description: >
-  E-commerce analytics: AOV, conversion rate, CLV, ROAS, cart abandonment rate.
+  E-commerce metrics analysis — AOV, conversion rate, CLV, ROAS, and cart
+  abandonment — delivered as a dashboard with funnel visualization and
+  benchmark comparison, plus browser verification that GA4, Meta Pixel, and
+  GTM tracking fire correctly. TRIGGER: "métricas da loja", "qual é o AOV",
+  "store analytics", "conversion rate da loja", "verifica o tracking GA4",
+  "/ecom analytics". SKIP: cross-channel campaign reporting ->
+  marketing/analytics-report (campaign-level, not store-level metrics);
+  diagnosing WHY conversion is low and building a test backlog
+  -> ecom/cro-optimize (research-driven optimization, not measurement).
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/ecom/skills/browse-competitor/SKILL.md

@@ -1,9 +1,16 @@
 ---
 name: ecom/browse-competitor
 description: >
-  Navigate a competitor's e-commerce site and extract structured intelligence:
-  product categories, price ranges, promotions, layout patterns, and screenshots.
-  Requires browser integration (claude --chrome or /chrome).
+  Navigates a competitor's e-commerce site with browser integration and
+  extracts structured intelligence — product categories, price ranges,
+  promotions, layout patterns, payment and shipping info — with screenshots
+  into an Obsidian report; falls back to WebFetch when no browser is
+  available. TRIGGER: "espia a loja do concorrente", "analisa o site da
+  concorrência", "browse competitor store", "vê os preços deles", "/ecom
+  browse-competitor <url>". SKIP: strategic competitive landscape without live
+  navigation -> marketing/competitor-analysis (research-based positioning, no
+  browser needed); auditing YOUR OWN store -> ecom/store-audit (5-agent audit
+  of the store you control).
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 

package/departments/ecom/skills/cart-recovery/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: ecom/cart-recovery
 description: >
-  Cart abandonment email sequence: 3 emails (1h, 24h, 72h) with urgency escalation.
+  Designs a cart abandonment recovery email sequence — 3 emails at 1h, 24h,
+  and 72h with urgency escalation — delivering subject lines, body copy,
+  timing, and incentive strategy. TRIGGER: "carrinho abandonado", "recupera
+  carrinhos abandonados", "abandoned cart emails", "sequência de recuperação
+  de carrinho", "/ecom cart-recovery". SKIP: broader nurture or promotional
+  email flows -> landing/email-sequence (persuasion sequences beyond cart
+  abandonment); deciding WHICH customers to target by value first
+  -> ecom/rfm-segment (segmentation precedes the flow).
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---