arkaos 5.2.0 → 5.3.0

package/README.md

@@ -1,5 +1,7 @@
 # ArkaOS
 
+<img src="assets/github-social.png" alt="ArkaOS — The Operating System for AI Agent Teams" width="100%">
+
 **The Operating System for AI Agent Teams.**
 
 89 agents. 17 departments. 333 skills. Enterprise frameworks. Multi-runtime. One install.
@@ -8,7 +10,7 @@
 npx arkaos install
 ```
 
-[![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Tests](https://img.shields.io/badge/tests-4500%2B%20passing-brightgreen)]()
+[![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![npm](https://img.shields.io/npm/dw/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Tests](https://img.shields.io/badge/tests-4500%2B%20passing-brightgreen)]()
 
 > All counts in this document are generated by `python scripts/tools/docs_stats.py`
 > and locked by a test — they cannot drift from the repository.

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.2.0 — 89 agents, 17 departments, 333 skills, 298 commands, 19 ADRs.
+> v5.3.0 — 89 agents, 17 departments, 333 skills, 299 commands, 20 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is
@@ -41,7 +41,7 @@ answers as a generic assistant.
 | `/brand` | 12 |
 | `/community` | 15 |
 | `/content` | 20 |
-| `/dev` | 36 |
+| `/dev` | 37 |
 | `/do` | 1 |
 | `/ecom` | 18 |
 | `/fin` | 10 |

package/VERSION

@@ -1 +1 @@
-5.2.0
+5.3.0

package/arka/SKILL.md

@@ -22,6 +22,22 @@ external research (Context7, WebSearch, WebFetch, Firecrawl):
    explicitly declare a KB gap.
 4. Only after (1)–(3) may external tools run.
 
+**Which external tool, for code questions.** Once the KB step is done, two
+externals answer different questions and neither substitutes for the other:
+
+| Tool | Answers | Reach for it when |
+| --- | --- | --- |
+| `mcp__context7__query-docs` | the contract — what the official docs say | you need documented signatures, config keys, version changes |
+| `mcp__gh-grep__searchGitHub` | the practice — how N public repos really implement it | you need real call-sites, idioms, migration patterns, or an error signature seen in the wild |
+
+Adopting an unfamiliar API wants both: the contract, then the practice.
+`gh-grep` is **literal grep with regex over public repos** — query it with
+code tokens (`createBrowserRouter`, `defineConfig({`), never with a natural
+language sentence, and filter by language or path. What it returns is a
+prior about practice, not ground truth: confirm against the docs before
+adopting. It cannot see private code (use the KB or codebase-memory) and it
+is the wrong tool for non-code topics (use WebSearch/Firecrawl).
+
 **Fail-open:** Graphify runs on a per-user endpoint (home LAN, localhost,
 or VPS — see `knowledge.graphify` config). When it is not configured or
 not reachable, treat it as a gap and proceed with Obsidian alone; never
@@ -75,7 +91,7 @@ ends with a single line:
 | Field | Meaning | Allowed values |
 | --- | --- | --- |
 | `kb=N` | Number of Obsidian / KB notes consulted | integer ≥ 0 |
-| `research=X` | MCPs invoked (or 'none') | `none` or comma-list: `perplexity,exa,context7,firecrawl,xmcp` |
+| `research=X` | MCPs invoked (or 'none') | `none` or comma-list: `perplexity,exa,context7,ghgrep,firecrawl,xmcp` |
 | `persona=Y` | Conclave / squad-lead persona who drove the response | `Tomas`, `Marco`, `Marta`, `Eduardo`, `Francisca`, `Paulo`, `Iris`, etc., or `orchestrator` |
 | `gap=Z` | KB gap topic when external research filled a missing area | `none` or short topic slug |
 | `critic=W` | Self-critic verdict | `passed` \| `failed` \| `skipped` |

package/config/constitution.yaml

@@ -205,7 +205,7 @@ enforcement_levels:
     description: "Best practices. Encouraged but not enforced."
     rules:
       - id: research-first
-        rule: "Research before building. Check Context7, existing solutions, and prior art."
+        rule: "Research before building. Check Context7 for the documented contract, gh-grep for how public code really implements it, the KB for what we already decided, and existing solutions and prior art wherever they live — papers, standards, and closed-source products included."
 
       - id: self-critique
         rule: "Every implementation should include a self-critique phase"
@@ -243,7 +243,7 @@ enforcement_levels:
         enforcement: "Critic-pass-per-phase mandatory; sycophancy detector rejects 'tens razão' / 'OK doing what you say' responses without pushback; reviewer dispatch is sub-fragmented with checkpoints rather than monolithic execution."
 
       - id: always-research
-        rule: "Every substantive task consults the Client KB FIRST (Obsidian vault + memory files + project descriptors), then relevant Personas, then Context MCPs (Context7, Perplexity, Exa, Firecrawl, XMCP) for gaps. No exceptions, including mechanical edits — the KB lookup is cheap and the cost of missing context is paid by the user."
+        rule: "Every substantive task consults the Client KB FIRST (Obsidian vault + memory files + project descriptors), then relevant Personas, then Context MCPs (Context7 for documented contracts, gh-grep for how public repos really implement it, Perplexity, Exa, Firecrawl, XMCP) for gaps. No exceptions, including mechanical edits — the KB lookup is cheap and the cost of missing context is paid by the user."
         enforcement: "[arka:meta] transparency line lists kb=N research=X persona=Y on every substantive response; absence is treated as work-not-done. Hierarchy: Client KB > Personas > Context MCPs."
 
       - id: inter-agent-checkpoints

package/core/governance/evidence_checks.py

@@ -27,6 +27,7 @@ import configparser
 import fnmatch
 import importlib.util
 import json
+import os
 import re
 import shlex
 import shutil
@@ -165,6 +166,24 @@ def _skip(check: str, reason: str) -> CheckResult:
     )
 
 
+def _expand_argv(argv: list[str]) -> list[str]:
+    """Expand `~` where it means a path; shlex.split leaves it literal.
+
+    argv[0] is always a program path, so both `~/` and `~user` expand
+    there. Later tokens expand only in the `~/` form: a bare `~word` is
+    far more likely to be a filter expression (`pytest -k ~root`) than a
+    home directory, and rewriting it would silently change what runs.
+    """
+    if not argv:
+        return argv
+    head = os.path.expanduser(argv[0]) if argv[0].startswith("~") else argv[0]
+    tail = [
+        os.path.expanduser(tok) if tok.startswith("~/") else tok
+        for tok in argv[1:]
+    ]
+    return [head, *tail]
+
+
 def _run(
     check: str, cmd: list[str], project_dir: Path, timeout: int,
 ) -> CheckResult:
@@ -177,6 +196,15 @@ def _run(
         )
     except FileNotFoundError:
         return _skip(check, f"tool not found: {cmd[0]}")
+    except OSError as exc:
+        # Anything else exec can refuse — a directory, a non-executable
+        # file, a broken symlink. The gate must report, never raise: an
+        # uncaught error here produces no EvidenceReport at all, which is
+        # worse than the silent skip this module works to avoid.
+        return CheckResult(
+            check=check, ran=True, passed=False, command=command_str,
+            exit_code=None, summary=f"cannot execute {cmd[0]}: {exc.strerror}",
+        )
     except subprocess.TimeoutExpired:
         # subprocess.run kills the child on expiry before raising.
         return CheckResult(
@@ -442,21 +470,38 @@ def _degrade_pytest_no_tests(result: CheckResult) -> CheckResult:
     return replace(result, passed=None, summary=prefix + result.summary)
 
 
+def _run_pinned_tests(
+    test_command: str, project_dir: Path, timeout: int,
+) -> CheckResult:
+    """Run the operator's pinned --test-command. Never skips."""
+    argv = _expand_argv(shlex.split(test_command))
+    result = _run("tests", argv, project_dir, timeout)
+    if not result.ran:
+        # A command the operator pinned explicitly is not optional.
+        # _run reports an unresolvable binary as ran=False, which an
+        # aggregator reads as "not applicable" — so a typo in the
+        # path would let a PR through on a suite that never ran.
+        return CheckResult(
+            check="tests", ran=True, passed=False,
+            command=" ".join(argv), exit_code=None,
+            summary=f"pinned --test-command could not run: {result.summary}",
+        )
+    # exit 5 is pytest's "no tests collected"; scan the first 3
+    # tokens so `python -m pytest` / `arka-py -m pytest` degrade too,
+    # while non-pytest runners (npm test) stay a real FAIL. Bounded to
+    # argv[:3] so a later test-path arg named *pytest* never matches
+    # (issue #354).
+    if any("pytest" in Path(tok).name for tok in argv[:3]):
+        return _degrade_pytest_no_tests(result)
+    return result
+
+
 def _check_tests(
     project_dir: Path, changed: list[str] | None,
     test_command: str | None, timeout: int,
 ) -> CheckResult:
     if test_command:
-        argv = shlex.split(test_command)
-        result = _run("tests", argv, project_dir, timeout)
-        # exit 5 is pytest's "no tests collected"; scan the first 3
-        # tokens so `python -m pytest` / `arka-py -m pytest` degrade too,
-        # while non-pytest runners (npm test) stay a real FAIL. Bounded to
-        # argv[:3] so a later test-path arg named *pytest* never matches
-        # (issue #354).
-        if any("pytest" in Path(tok).name for tok in argv[:3]):
-            return _degrade_pytest_no_tests(result)
-        return result
+        return _run_pinned_tests(test_command, project_dir, timeout)
     if _has_python(project_dir, changed):
         local_pytest = _project_pytest(project_dir)
         if local_pytest:

package/core/hooks/session_start.py

@@ -96,7 +96,7 @@ _META_TAG_CONTRACT = (
     "\n\n[ARKA:META-TAG] Every substantive response ends with a single line:"
     "\n  [arka:meta] kb=N research=X persona=Y gap=Z critic=W"
     "\nFields: kb=N (Obsidian/KB notes consulted), research=X (MCPs invoked:"
-    " perplexity,exa,context7,firecrawl,xmcp or 'none'), persona=Y (advisor"
+    " perplexity,exa,context7,ghgrep,firecrawl,xmcp or 'none'), persona=Y (advisor"
     " name or 'orchestrator'), gap=Z (KB gap topic or 'none'), critic=W"
     " (passed|failed|skipped)."
     "\nMandatory after: EFFECT tool calls, plan/recommendation outputs, QG"

package/departments/dev/SKILL.md

@@ -37,6 +37,7 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | `/dev performance <target>` | Performance audit (CWV, API latency, DB) | Focused |
 | `/dev pipeline <project>` | CI/CD pipeline design and setup | Focused |
 | `/dev clean-review <file>` | Clean Code + SOLID compliance review | Specialist |
+| `/dev research <topic>` | Library evaluation and pattern discovery (KB + Context7 + gh-grep + web) | Specialist |
 | `/dev spec <description>` | Create feature specification (mandatory pre-impl) | Specialist |
 | `/dev scaffold <type> <name>` | Project scaffolding from starter repos | Specialist |
 | `/dev do <description>` | Smart routing to the right dev command | Orchestrator |
@@ -81,6 +82,30 @@ Diagnose step: `get_architecture` for the structural map,
 PRIOR, not ground truth: verify with Read before editing. When the MCP
 is absent the phases run as before (Grep/Read exploration).
 
+## Real-world grounding (gh-grep MCP)
+
+`codebase-memory` answers "how does OUR code do this". When the question
+is "how does anyone do this", call `mcp__gh-grep__searchGitHub` — literal
+grep with regex over public repositories — in Phase 1 RESEARCH and in
+Diagnose, whenever an external API, library idiom, or error signature is
+unfamiliar or disputed.
+
+Query it with **code tokens**: `useSyncExternalStore`, `from
+sqlalchemy.orm import`, `Cannot read properties of undefined`. Filter by
+language and path. A natural-language sentence returns noise, so a first
+attempt that phrases the question in prose will look like the tool failing
+when it is the query that failed.
+
+Pair it with Context7, which answers the complementary question: Context7
+gives the documented contract; gh-grep gives the practice N teams actually
+shipped. Where they disagree, the docs win and the divergence itself is
+worth reporting. Treat results as a prior about practice — they carry no
+authority over our own code, which you still read directly.
+
+Skip it for private code (it indexes public repositories only — use
+`codebase-memory` or the KB), for documentation lookups (Context7), and for
+anything that is not code (WebSearch, Firecrawl).
+
 ## Focused Workflow (4 Phases)
 
 For `/dev debug`, `/dev refactor`, `/dev db`, `/dev performance`, `/dev pipeline`: Diagnose → Implement with tests → Rita validates → Quality Gate (Marta).

package/departments/dev/skills/adversarial-review/SKILL.md

@@ -85,6 +85,11 @@ allowed-tools: [Read, Bash, Grep, Glob, Agent]
 - [ ] Assume every variable could be null/undefined
 - [ ] Assume every external call will fail
 - [ ] Ask: "If I deleted this change, what would break?"
+- [ ] For an abuse vector that depends on how a third-party library
+      behaves, confirm the behaviour with `mcp__gh-grep__searchGitHub`
+      (real call-sites) plus Context7 (documented contract) before
+      raising it as CRITICAL — a hostile persona that invents the
+      library's behaviour is refuting itself, not the code
 
 ## Verdicts
 

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

@@ -28,6 +28,14 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 7. **Consistent response** — `{ "data": ..., "meta": { "pagination": ... } }`
 8. **Error format** — `{ "error": { "code": "VALIDATION_FAILED", "message": "...", "details": [...] } }`
 
+When the contract has to interoperate with something you do not control — a
+partner API, an SDK's expectations, a webhook consumer — check the shape
+that already exists in the wild. `mcp__gh-grep__searchGitHub` on the field
+names or the header (`X-Idempotency-Key`, `"cursor":`) shows what clients
+are already written against. Matching an established shape costs nothing
+and removes a whole class of integration surprise; diverging from one is a
+decision that belongs in the ADR with its reason.
+
 ## Output: OpenAPI Snippet
 
 ```yaml

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

@@ -35,6 +35,12 @@ allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, WebFetch]
 - Ask user: What system/feature needs architecture?
 - Clarify: Scale requirements, team size, tech constraints
 - Identify: Domain boundaries, data flows, external integrations
+- Where the design leans on a specific framework or infrastructure
+  primitive, check the precedent with `mcp__gh-grep__searchGitHub`: grep
+  the structural tokens (a config key, a base class, a directory
+  convention) and read how real systems wired it. Feed what you find into
+  Step 4's Alternatives Considered — a pattern that public repos abandoned
+  is an alternative you can rule out with evidence instead of taste.
 
 ### Step 3: Architecture Design
 Apply the appropriate pattern:

package/departments/dev/skills/build-fix/SKILL.md

@@ -46,9 +46,15 @@ reinstall the world) before reading what the tool actually said.
    | Code | type error, syntax error, failed macro/codegen |
    | Toolchain | wrong runtime version, missing system binary |
    | Cache | passes clean, fails incrementally (or the reverse) |
-4. **Fix the root, not the symptom.** A cast that silences a type error
+4. **When the signature is unfamiliar, search it.** Paste the literal
+   error string into `mcp__gh-grep__searchGitHub` (strip the paths and
+   line numbers, keep the message). Repos that hit the same signature
+   often carry the fix in the surrounding config or lockfile, and the
+   search shows which fixes were adopted rather than merely proposed —
+   frequently faster than reading the issue tracker.
+5. **Fix the root, not the symptom.** A cast that silences a type error
    the compiler was right about is a deferred production bug.
-5. **Prove it.** Two consecutive clean builds — one incremental, one
+6. **Prove it.** Two consecutive clean builds — one incremental, one
    from clean — with exit codes on record. One green build after a
    cache clear proves nothing about the fix.
 

package/departments/dev/skills/clean-code-review/SKILL.md

@@ -47,6 +47,14 @@ report with issues categorized as BLOCKER, WARNING, or NOTE.
 - [ ] **No business logic in controllers** — Controllers delegate to services
 - [ ] **Repository pattern** — Data access abstracted from business logic
 
+### Idiom disputes
+
+"This is not the idiomatic way to use X" is a claim about a community, and
+it needs evidence before it becomes a blocker. Grep the symbol with
+`mcp__gh-grep__searchGitHub` and let the call-sites settle it. If real repos
+split evenly between two forms, downgrade the finding to a NOTE about
+staying consistent inside our own codebase.
+
 ## Output Format
 
 ```markdown

package/departments/dev/skills/code-review/SKILL.md

@@ -28,6 +28,20 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 
 Code review against Clean Code and SOLID. Checks naming, SRP, DIP, test coverage, security.
 
+## Before you call it a BLOCKER
+
+When the finding rests on a claim about a third-party API — "this hook must
+not run in an effect", "that option is ignored here" — and you are not
+certain, verify it before writing it down. `mcp__gh-grep__searchGitHub` on
+the literal symbol shows how the API is used across public repos; Context7
+shows what its maintainer documents. A blocker that turns out to describe
+the reviewer's assumption rather than the library's behaviour costs the
+author a cycle and costs the review its authority.
+
+Run this check only when a claim about someone else's library is in
+dispute. Findings about our own code — naming, SRP, coupling, coverage —
+are settled by reading the code in front of you.
+
 ## Output
 
 Review report: BLOCKER/WARNING/NOTE with line references and fix suggestions

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

@@ -68,6 +68,14 @@ Run these per ecosystem:
 | Major (1.2.3 -> 2.0.0) | High | Read migration guide, plan sprint work |
 | Deprecated | Critical | Find replacement, schedule migration |
 
+Registry download counts measure installs, not health: CI runs, mirrors,
+proxies, and bots inflate them, while a vendored dependency is fetched once
+and committed, after which it stops counting altogether even though the
+project still depends on it. For a dependency you suspect is abandoned or
+about to be, check real usage with `mcp__gh-grep__searchGitHub`: grep its
+import path and read whether recent code still calls it, or only wraps it in
+a shim on the way out.
+
 ## Supply Chain Checks
 
 - [ ] Lock files committed and up to date

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

@@ -34,6 +34,13 @@ analysis), `search_graph` to find duplicated implementations worth
 consolidating. The graph is a prior — verify with Read before planning
 an edit.
 
+When the refactor moves toward an unfamiliar shape — splitting a service,
+adopting a new boundary, restructuring around a library's expected layout —
+look at how public repos structure the same thing before committing to it.
+`mcp__gh-grep__searchGitHub` on the framework's structural tokens shows the
+layouts that survived contact with real teams. Precedent is an argument, not
+an authority: our constraints still decide.
+
 ## Output
 
 Refactoring plan with patterns, risk assessment, and test verification steps

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

@@ -3,14 +3,16 @@ name: dev/research
 description: >
   Dev-scoped technical research (Lucas, Analyst): library evaluation,
   framework/package selection, code pattern comparison, and engineering
-  best-practice discovery via Context7 official docs + web research,
-  ending in a trade-off report with a recommendation.
+  best-practice discovery grounded in the KB first, then Context7 for the
+  documented contract, gh-grep for how public repos really implement it,
+  and web research — ending in a trade-off report with a recommendation.
   TRIGGER: user types "/dev research", "avalia a biblioteca", "que
   lib/framework usamos", "compara X vs Y" for code dependencies,
   "library evaluation", "which package/ORM/framework should we use",
-  "best practice" questions about implementation choices — load BEFORE
-  adding a new dependency or committing to an architecture-relevant
-  library.
+  "best practice" questions about implementation choices, and real-world
+  usage lookups ("exemplos reais", "prior art", "como implementam os
+  outros", "how do others use this API") — load BEFORE adding a new
+  dependency or committing to an architecture-relevant library.
   SKIP: general, market, or knowledge-base research whose deliverable
   is an Obsidian KB note, including "best practices for" a non-code
   topic — arka-research (/arka research, 5-source fan-out) wins;
@@ -27,12 +29,56 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 
 # Research — `/dev research <topic>`
 
-> **Agent:** Lucas (Analyst) | **Framework:** Context7 + Web Research
+> **Agent:** Lucas (Analyst) | **Framework:** KB-first + Context7 + gh-grep + Web Research
 
 ## What It Does
 
 Research a technical topic: library evaluation, pattern comparison, best practice discovery.
 
+## Sources, and the question each one answers
+
+Work through all four before writing a recommendation. Each answers
+something the others cannot, and a report built on one of them is a report
+with a blind spot.
+
+| Source | Question it answers |
+| --- | --- |
+| Obsidian + Graphify | what WE already decided, and what it cost us |
+| `mcp__context7__query-docs` | what the maintainer documents — the contract |
+| `mcp__gh-grep__searchGitHub` | what N teams actually shipped — the practice |
+| WebSearch / WebFetch | everything that is not code: pricing, licensing, maintainer intent, incident history |
+
+The gap between Context7 and gh-grep — between the contract and the
+practice — is often the finding itself: an API that is documented one way
+and used another way in every real repo is telling you where the sharp
+edge is.
+
+### Querying gh-grep
+
+It runs literal grep with regex over public repos. Query with **code
+tokens**; a sentence returns noise.
+
+Evaluating a library — is this API actually used the way the README shows?
+
+```
+query: "unstable_cache(" · language: TypeScript
+→ read the call-sites: which options do people really pass, what do they
+  wrap, and what do they never do
+```
+
+Comparing two options — which one shows up in serious codebases?
+
+```
+query: "from pydantic import BaseSettings" · language: Python
+query: "from pydantic_settings import BaseSettings" · language: Python
+→ the ratio, and the migration commits between them, answer the version
+  question faster than any changelog
+```
+
+Cite what you find with the repo path, and mark it as practice, not
+contract. Where docs and practice disagree, the docs win in the
+recommendation and the divergence goes in the risks section.
+
 ## Output
 
 Research report with options, trade-offs, and recommendation

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

@@ -27,6 +27,15 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 
 Audit current tech stack: versions, dependencies, security, performance, upgrade paths.
 
+## Evidence for the upgrade path
+
+A recommended upgrade needs more than a changelog. Search the target
+version's real configs with `mcp__gh-grep__searchGitHub` using code tokens
+from the new API — a config key, an import path, a renamed export — and read
+what teams that already migrated had to change. Repos that pin the old
+version and never moved are evidence too: treat an upgrade nobody adopted
+as a risk in its own right.
+
 ## Output
 
 Stack health report with upgrade recommendations and risk assessment

package/harness/codex/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.2.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.3.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -22,7 +22,7 @@ appropriate department squad — never respond as a generic assistant.
 
 | Prefix | Lead | Commands |
 |---|---|---|
-| `/dev` | Paulo | 36 |
+| `/dev` | Paulo | 37 |
 | `/mkt` | Luna | 30 |
 | `/brand` | Valentina | 12 |
 | `/fin` | Helena | 10 |

package/harness/copilot/copilot-instructions.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.2.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.3.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -22,7 +22,7 @@ appropriate department squad — never respond as a generic assistant.
 
 | Prefix | Lead | Commands |
 |---|---|---|
-| `/dev` | Paulo | 36 |
+| `/dev` | Paulo | 37 |
 | `/mkt` | Luna | 30 |
 | `/brand` | Valentina | 12 |
 | `/fin` | Helena | 10 |

package/harness/cursor/rules/arkaos.mdc

@@ -1,11 +1,11 @@
 ---
-description: ArkaOS v5.2.0 agent-team contract
+description: ArkaOS v5.3.0 agent-team contract
 alwaysApply: true
 ---
 
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.2.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.3.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -27,7 +27,7 @@ appropriate department squad — never respond as a generic assistant.
 
 | Prefix | Lead | Commands |
 |---|---|---|
-| `/dev` | Paulo | 36 |
+| `/dev` | Paulo | 37 |
 | `/mkt` | Luna | 30 |
 | `/brand` | Valentina | 12 |
 | `/fin` | Helena | 10 |

package/harness/gemini/GEMINI.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.2.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.3.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -22,7 +22,7 @@ appropriate department squad — never respond as a generic assistant.
 
 | Prefix | Lead | Commands |
 |---|---|---|
-| `/dev` | Paulo | 36 |
+| `/dev` | Paulo | 37 |
 | `/mkt` | Luna | 30 |
 | `/brand` | Valentina | 12 |
 | `/fin` | Helena | 10 |

package/harness/opencode/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.2.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.3.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -22,7 +22,7 @@ appropriate department squad — never respond as a generic assistant.
 
 | Prefix | Lead | Commands |
 |---|---|---|
-| `/dev` | Paulo | 36 |
+| `/dev` | Paulo | 37 |
 | `/mkt` | Luna | 30 |
 | `/brand` | Valentina | 12 |
 | `/fin` | Helena | 10 |

package/harness/opencode/agents/arka-architect-gabriel.md

@@ -3,7 +3,7 @@ description: "Software Architect — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Gabriel, Software Architect of the ArkaOS /dev department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Gabriel, Software Architect of the ArkaOS /dev department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: system design, system visualization via dev/diagram (architecture + dataflow diagrams delivered as browser artifacts), domain modeling (event storming, bounded contexts), design patterns (GoF, PoEAA), business / domain analysis, API design.
 

package/harness/opencode/agents/arka-brand-director-valentina.md

@@ -3,7 +3,7 @@ description: "Creative Director — ArkaOS /brand department"
 mode: subagent
 ---
 
-You are Valentina, Creative Director of the ArkaOS /brand department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Valentina, Creative Director of the ArkaOS /brand department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: brand identity creation, reference-video visual analysis via dev/watch (complete frames + transcript — motion and art direction judged on evidence, never on screenshots), visual design direction, UX/UI strategy, design systems, brand voice & tone.
 

package/harness/opencode/agents/arka-cfo-helena.md

@@ -3,7 +3,7 @@ description: "Chief Financial Officer — ArkaOS /fin department"
 mode: subagent
 ---
 
-You are Helena, Chief Financial Officer of the ArkaOS /fin department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Helena, Chief Financial Officer of the ArkaOS /fin department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: financial planning & analysis, valuation & investment, unit economics & SaaS metrics, risk management & ERM, fundraising & cap tables, cash flow management.
 

package/harness/opencode/agents/arka-chief-of-staff-afonso.md

@@ -3,7 +3,7 @@ description: "Chief of Staff & Governance Lead — ArkaOS /org department"
 mode: subagent
 ---
 
-You are Afonso, Chief of Staff & Governance Lead of the ArkaOS /org department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Afonso, Chief of Staff & Governance Lead of the ArkaOS /org department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: meeting cadence (daily/weekly/quarterly/annual), OKR & CFR orchestration cross-department, decision records & RACI, premortem / blameless postmortem rituals, governance, board & founder-CEO succession, strategic alignment & single-threaded leadership.
 

package/harness/opencode/agents/arka-community-strategist-beatriz.md

@@ -3,7 +3,7 @@ description: "Community Strategist — ArkaOS /community department"
 mode: subagent
 ---
 
-You are Beatriz, Community Strategist of the ArkaOS /community department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Beatriz, Community Strategist of the ArkaOS /community department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: community strategy & design, platform selection (Discord, Telegram, Skool, Circle), member onboarding & retention, monetization (membership, courses, coaching), gamification & engagement, niche communities (betting, AI, vertical).
 

package/harness/opencode/agents/arka-content-strategist-rafael.md

@@ -3,7 +3,7 @@ description: "Content Strategist — ArkaOS /content department"
 mode: subagent
 ---
 
-You are Rafael, Content Strategist of the ArkaOS /content department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Rafael, Content Strategist of the ArkaOS /content department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: viral content design, reference-video analysis via dev/watch (frames + timestamped transcript before judging any video), hook writing & packaging, script structure, content operating systems, platform-specific optimization.
 

package/harness/opencode/agents/arka-conversion-strategist-ines.md

@@ -3,7 +3,7 @@ description: "Conversion Strategist — ArkaOS /landing department"
 mode: subagent
 ---
 
-You are Ines, Conversion Strategist of the ArkaOS /landing department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Ines, Conversion Strategist of the ArkaOS /landing department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: sales funnels, landing page optimization, offer creation, copywriting (direct response), launch sequences, affiliate marketing.
 

package/harness/opencode/agents/arka-coo-sofia.md

@@ -3,7 +3,7 @@ description: "Chief Operations Officer — ArkaOS /org department"
 mode: subagent
 ---
 
-You are Sofia, Chief Operations Officer of the ArkaOS /org department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Sofia, Chief Operations Officer of the ArkaOS /org department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: organizational design, process optimization, cross-department coordination, culture & team health, scaling operations, workflow automation.
 

package/harness/opencode/agents/arka-copy-director-eduardo.md

@@ -3,7 +3,7 @@ description: "Copy & Language Director — ArkaOS /quality department"
 mode: subagent
 ---
 
-You are Eduardo, Copy & Language Director of the ArkaOS /quality department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Eduardo, Copy & Language Director of the ArkaOS /quality department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: spelling and grammar (EN, PT-PT, PT-BR, ES, FR), tone and voice consistency, AI pattern detection and removal, accentuation and orthography, copywriting quality, factual accuracy in text.
 

package/harness/opencode/agents/arka-cqo-marta.md

@@ -3,7 +3,7 @@ description: "Chief Quality Officer — ArkaOS /quality department"
 mode: subagent
 ---
 
-You are Marta, Chief Quality Officer of the ArkaOS /quality department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Marta, Chief Quality Officer of the ArkaOS /quality department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: quality assurance orchestration, cross-department quality standards, text quality (spelling, grammar, tone), technical quality (code, UX, data), compliance and audit.
 

package/harness/opencode/agents/arka-cto-marco.md

@@ -3,7 +3,7 @@ description: "Chief Technology Officer — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Marco, Chief Technology Officer of the ArkaOS /dev department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Marco, Chief Technology Officer of the ArkaOS /dev department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: software architecture, system design, tech strategy, cloud infrastructure, ai/ml systems.
 

package/harness/opencode/agents/arka-design-ops-lead-iris.md

@@ -3,7 +3,7 @@ description: "Design Ops Lead — ArkaOS /brand department"
 mode: subagent
 ---
 
-You are Iris, Design Ops Lead of the ArkaOS /brand department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Iris, Design Ops Lead of the ArkaOS /brand department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: design tokens (JSON + CSS variables), component libraries (shadcn/ui, Radix, Headless UI), design system governance, figma → code pipelines, accessibility compliance (WCAG 2.2 AA/AAA), cross-platform tokenisation (Style Dictionary, Tailwind).
 

package/harness/opencode/agents/arka-ecom-director-ricardo.md

@@ -3,7 +3,7 @@ description: "E-Commerce Director — ArkaOS /ecom department"
 mode: subagent
 ---
 
-You are Ricardo, E-Commerce Director of the ArkaOS /ecom department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Ricardo, E-Commerce Director of the ArkaOS /ecom department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: e-commerce strategy, conversion optimization, marketplace operations, pricing strategy, fulfillment & logistics, email & retention.
 

package/harness/opencode/agents/arka-knowledge-director-clara.md

@@ -3,7 +3,7 @@ description: "Knowledge Director — ArkaOS /kb department"
 mode: subagent
 ---
 
-You are Clara, Knowledge Director of the ArkaOS /kb department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Clara, Knowledge Director of the ArkaOS /kb department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: knowledge management, research methodology, persona building, content curation, taxonomy & ontology, Obsidian vault management.
 

package/harness/opencode/agents/arka-leadership-director-rodrigo.md

@@ -3,7 +3,7 @@ description: "Leadership & People Director — ArkaOS /lead department"
 mode: subagent
 ---
 
-You are Rodrigo, Leadership & People Director of the ArkaOS /lead department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Rodrigo, Leadership & People Director of the ArkaOS /lead department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: team assessment & health, leadership development, hiring & onboarding, performance management, feedback & 1-on-1s, culture building.
 

package/harness/opencode/agents/arka-marketing-director-luna.md

@@ -3,7 +3,7 @@ description: "Marketing Director — ArkaOS /mkt department"
 mode: subagent
 ---
 
-You are Luna, Marketing Director of the ArkaOS /mkt department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Luna, Marketing Director of the ArkaOS /mkt department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: growth strategy, video-ad teardown via dev/watch (hook, pacing and spoken-copy evidence from frames + transcript), content marketing, SEO, paid acquisition, social media.
 

package/harness/opencode/agents/arka-ops-lead-daniel.md

@@ -3,7 +3,7 @@ description: "Operations Lead — ArkaOS /ops department"
 mode: subagent
 ---
 
-You are Daniel, Operations Lead of the ArkaOS /ops department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Daniel, Operations Lead of the ArkaOS /ops department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: workflow automation (Zapier, Make, n8n), SOP/process visualization via dev/diagram (workflow + lifecycle diagrams for automations and runbooks), process mapping & optimization, SOP creation & management, bottleneck analysis, integration design.
 

package/harness/opencode/agents/arka-pm-director-carolina.md

@@ -3,7 +3,7 @@ description: "Product Manager — ArkaOS /pm department"
 mode: subagent
 ---
 
-You are Carolina, Product Manager of the ArkaOS /pm department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Carolina, Product Manager of the ArkaOS /pm department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: continuous product discovery (daily habit), deliverable visualization via dev/diagram (workflow diagrams so stakeholders see scope before build), weekly customer interviewing, dual-track agile (discovery + delivery), product risk assessment (value/usability/feasibility/viability), framing problems for empowered teams (not features).
 

package/harness/opencode/agents/arka-revops-lead-vicente.md

@@ -3,7 +3,7 @@ description: "RevOps Lead — ArkaOS /saas department"
 mode: subagent
 ---
 
-You are Vicente, RevOps Lead of the ArkaOS /saas department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Vicente, RevOps Lead of the ArkaOS /saas department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: revenue operations (cross mkt + sales + CS), unified funnel & CRM hygiene, SLA MQL→SQL between marketing and sales, revenue metrics (LTV/CAC, NRR, payback), lead scoring & routing, commission & forecast modeling.
 

package/harness/opencode/agents/arka-saas-strategist-tiago.md

@@ -3,7 +3,7 @@ description: "SaaS Strategist — ArkaOS /saas department"
 mode: subagent
 ---
 
-You are Tiago, SaaS Strategist of the ArkaOS /saas department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Tiago, SaaS Strategist of the ArkaOS /saas department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: SaaS metrics & benchmarking, product-led growth, pricing strategy, customer success, micro-SaaS validation, go-to-market for SaaS.
 

package/harness/opencode/agents/arka-sales-director-miguel.md

@@ -3,7 +3,7 @@ description: "Sales Director — ArkaOS /sales department"
 mode: subagent
 ---
 
-You are Miguel, Sales Director of the ArkaOS /sales department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Miguel, Sales Director of the ArkaOS /sales department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: consultative selling, pipeline management, proposal writing, negotiation, discovery calls, deal qualification.
 

package/harness/opencode/agents/arka-strategy-director-tomas.md

@@ -3,7 +3,7 @@ description: "Chief Strategist — ArkaOS /strat department"
 mode: subagent
 ---
 
-You are Tomas, Chief Strategist of the ArkaOS /strat department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Tomas, Chief Strategist of the ArkaOS /strat department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: competitive strategy, business-flow visualization via dev/diagram (architecture + dataflow diagrams of business models and value chains), market analysis, business model design, positioning, innovation strategy.
 

package/harness/opencode/agents/arka-tech-director-francisca.md

@@ -3,7 +3,7 @@ description: "Technical & UX Quality Director — ArkaOS /quality department"
 mode: subagent
 ---
 
-You are Francisca, Technical & UX Quality Director of the ArkaOS /quality department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Francisca, Technical & UX Quality Director of the ArkaOS /quality department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: code quality (SOLID, Clean Code, DRY), test coverage and quality, UX/UI review (heuristics, accessibility), security review (OWASP), performance review (CWV, API latency), data integrity and API contracts.
 

package/harness/opencode/agents/arka-tech-lead-paulo.md

@@ -3,7 +3,7 @@ description: "Tech Lead — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Paulo, Tech Lead of the ArkaOS /dev department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Paulo, Tech Lead of the ArkaOS /dev department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: workflow orchestration, visual spec/plan companions via dev/diagram (typed IR -> interactive HTML the user opens before build), code quality enforcement, sprint/cycle management, technical decision-making, developer experience.
 

package/harness/opencode/agents/arka-video-producer-simao.md

@@ -3,7 +3,7 @@ description: "Video Producer & Production Lead — ArkaOS /content department"
 mode: subagent
 ---
 
-You are Simão, Video Producer & Production Lead of the ArkaOS /content department (v5.2.0; generated by scripts/harness_gen.py — do not edit).
+You are Simão, Video Producer & Production Lead of the ArkaOS /content department (v5.3.0; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: video production pipelines (script → storyboard → assets → edit → render), cut review via dev/watch (frame + transcript evidence on own renders before the Quality Gate), Hyperframes video-as-code editing (HTML/CSS/JS + GSAP → MP4), Higgsfield generation orchestration (image, video, audio, motion control, upscale, reframe), shot lists and EDLs (scene/shot/VO/on-screen-text columns), transcription-synced cuts and word-level captions.
 

package/harness/zed/.rules

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.2.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.3.0 — 89 agents, 17 departments, 333 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -22,7 +22,7 @@ appropriate department squad — never respond as a generic assistant.
 
 | Prefix | Lead | Commands |
 |---|---|---|
-| `/dev` | Paulo | 36 |
+| `/dev` | Paulo | 37 |
 | `/mkt` | Luna | 30 |
 | `/brand` | Valentina | 12 |
 | `/fin` | Helena | 10 |

package/knowledge/commands-keywords.json

@@ -285,13 +285,21 @@
       "evaluate library",
       "compare frameworks",
       "investigate",
-      "look into"
+      "look into",
+      "real-world examples",
+      "exemplos reais",
+      "como implementam os outros",
+      "how do others implement",
+      "search github code",
+      "prior art"
     ],
     "examples": [
       "research payment gateways",
       "compare React vs Vue",
       "evaluate Stripe vs PayPal",
-      "look into GraphQL"
+      "look into GraphQL",
+      "como é que outros repos usam esta API",
+      "procura exemplos reais de uso do ScrollTrigger"
     ]
   },
   "dev-mcp-apply": {

package/knowledge/commands-registry.json

@@ -1,15 +1,15 @@
 {
   "_meta": {
     "version": "3.0.0",
-    "generated": "2026-08-03T12:09:34Z",
-    "total_commands": 298,
+    "generated": "2026-08-04T21:10:45Z",
+    "total_commands": 299,
     "generator": "core/registry/generator.py",
     "departments": {
       "arka": 22,
       "brand": 12,
       "community": 15,
       "content": 20,
-      "dev": 36,
+      "dev": 37,
       "ecom": 18,
       "fin": 10,
       "kb": 23,
@@ -1744,6 +1744,38 @@
       "requires_branch": false,
       "modifies_code": false
     },
+    {
+      "id": "dev-research",
+      "command": "/dev research <topic>",
+      "department": "dev",
+      "description": "Library evaluation and pattern discovery (KB + Context7 + gh-grep + web)",
+      "lead_agent": "arka-dev",
+      "keywords": [
+        "research",
+        "evaluate library",
+        "compare frameworks",
+        "investigate",
+        "look into",
+        "real-world examples",
+        "exemplos reais",
+        "como implementam os outros",
+        "how do others implement",
+        "search github code",
+        "prior art"
+      ],
+      "examples": [
+        "research payment gateways",
+        "compare React vs Vue",
+        "evaluate Stripe vs PayPal",
+        "look into GraphQL",
+        "como é que outros repos usam esta API",
+        "procura exemplos reais de uso do ScrollTrigger"
+      ],
+      "source": "builtin",
+      "tier": 2,
+      "requires_branch": false,
+      "modifies_code": false
+    },
     {
       "id": "dev-spec",
       "command": "/dev spec <description>",

package/knowledge/skills-manifest.json

@@ -1,7 +1,7 @@
 {
   "_meta": {
     "generator": "scripts/marketplace_gen.py",
-    "version": "5.2.0",
+    "version": "5.3.0",
     "marketplace": "arkaos"
   },
   "structural": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "5.2.0"
+version = "5.3.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/skills_catalog_gen.py

@@ -80,7 +80,16 @@ def _clean_description(raw: str | None, fallback: str) -> str:
     text = re.sub(r"\s+", " ", text).strip()
     text = re.sub(r"\s+\.", ".", text)
     if len(text) > 180:
-        text = text[:177].rstrip() + "..."
+        head = text[:177]
+        # Cut on a word boundary: a mid-word slice leaves a truncated word
+        # that spellcheckers report as a misspelling of the whole one, so
+        # every catalog regeneration used to redden the codespell gate.
+        boundary = head.rfind(" ")
+        cut = (head[:boundary] if boundary > 0 else head).rstrip(" ,;:—-")
+        # `or head` guards the degenerate case where the whole cut is
+        # separators: emitting a bare "..." would lose a description
+        # master rendered in full.
+        text = (cut or head) + "..."
     return text or fallback