arkaos 4.24.0 → 4.25.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-86 agents. 17 departments. 294 skills. Enterprise frameworks. Multi-runtime. One install.
+86 agents. 17 departments. 298 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.24.0 — 86 agents, 17 departments, 294 skills, 270 commands, 16 ADRs.
+> v4.25.0 — 86 agents, 17 departments, 298 skills, 270 commands, 16 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-4.24.0
+4.25.0

package/arka/SKILL.md

@@ -47,7 +47,7 @@ complementary, not alternatives.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 86 agents. 17 departments. 294 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 86 agents. 17 departments. 298 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/bin/arka

@@ -66,6 +66,14 @@ case "${1:-}" in
     ;;
   doctor)
     shift
+    # Issue #358: the node doctor is canonical (engine/venv/hooks/security
+    # + the migrated Claude-layer checks). The bash doctor only audits the
+    # legacy v1 layout — keep it strictly as the no-node fallback.
+    if command -v npx &>/dev/null; then
+      npx arkaos doctor "$@"
+      exit $?
+    fi
+    echo "npx not found — falling back to the legacy v1 doctor (limited scope)." >&2
     bash "$HOME/.local/bin/arka-doctor" "$@"
     exit $?
     ;;

package/config/claude-agents/shadcn-padronizer.md

@@ -1,15 +1,15 @@
 ---
 name: shadcn-padronizer
 description: >
-  Leo — Component Library Padronizer (brand squad). Executes: shadcn/ui component generation and customisation, Radix UI primitives integration, Tailwind configuration and theme tokens, CVA variants and slot patterns.
+  Leo — Component Library Standardizer (brand squad). Executes: shadcn/ui component generation and customisation, Radix UI primitives integration, Tailwind configuration and theme tokens, CVA variants and slot patterns.
 model: sonnet
 ---
 
 <!-- generated by core/agents/behavioral_compiler.py from departments/brand/agents/design-ops/shadcn-padronizer.yaml — DO NOT EDIT; edit the YAML and re-run -->
 
-# Leo — Component Library Padronizer
+# Leo — Component Library Standardizer
 
-You are Leo, Component Library Padronizer of the brand squad (Tier 2). What drives you: One canonical component, used everywhere, evolving cleanly. The failure you exist to prevent: Five teams shipping five Button components that diverge over a quarter.
+You are Leo, Component Library Standardizer of the brand squad (Tier 2). What drives you: One canonical component, used everywhere, evolving cleanly. The failure you exist to prevent: Five teams shipping five Button components that diverge over a quarter.
 
 ## How you work
 

package/departments/brand/agents/design-ops/shadcn-padronizer.yaml

@@ -1,6 +1,6 @@
 id: shadcn-padronizer-leo
 name: Leo
-role: Component Library Padronizer
+role: Component Library Standardizer
 department: brand
 tier: 2
 model: sonnet

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

@@ -0,0 +1,122 @@
+---
+name: dev/build-fix
+description: >
+  Systematic build-failure diagnosis: read the FIRST error bottom-up,
+  reproduce it in isolation, classify it (dependency, config, code,
+  toolchain, cache), fix the root cause, and prove the fix with two
+  clean builds — with per-ecosystem playbooks for the failure
+  signatures of Laravel/PHP, Node/TS, Vue/Nuxt, React/Next, and Python.
+  TRIGGER: "/dev build-fix", "the build is broken", "o build está a
+  falhar", "compila localmente mas falha no CI", "npm run build
+  rebenta", "composer install falha", "arranja o build"; any red build
+  whose error output exists. SKIP: the code builds but tests fail ->
+  dev/code-review or dev/app-test wins; designing the pipeline itself
+  -> dev/ci-cd-pipeline wins; a production outage -> dev/incident wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Build Fix — `/dev build-fix`
+
+> **Agent:** Paulo (Tech Lead) | **Framework:** Root-cause classification, first-error discipline
+
+A failing build is the most honest bug report you will ever receive:
+deterministic, reproducible, and pointing at itself. Almost every hour
+lost to a broken build is lost the same way — fixing the LAST error on
+the screen, which is usually a cascade symptom of the first one, or
+reaching for the folk remedy (delete the lockfile, clear every cache,
+reinstall the world) before reading what the tool actually said.
+
+## Method
+
+1. **Find the first error.** Scroll past the cascade; the root error is
+   the earliest one, and everything after it is noise until proven
+   otherwise.
+2. **Reproduce in isolation.** Run the failing step alone, from a clean
+   shell, with the project's pinned tool versions. A build that only
+   fails inside CI is still reproducible — replicate the CI's inputs
+   (env vars, lockfile, node/php/python version) locally before
+   touching anything.
+3. **Classify** the root error into exactly one bucket:
+   | Bucket | Signature |
+   |---|---|
+   | Dependency | resolver conflicts, missing package, lockfile drift |
+   | Config | tool config rejects input, wrong paths, env var absent |
+   | 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
+   the compiler was right about is a deferred production bug.
+5. **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.
+
+## Ecosystem playbooks
+
+### Laravel / PHP
+
+- `Class not found` after moving a file → regenerate the autoload map
+  (`composer dump-autoload`); if it persists, the namespace does not
+  match the path — fix the namespace, not the autoloader.
+- `composer install` resolver conflict → read WHICH two constraints
+  collide before touching version pins; widening the wrong one
+  downgrades half the tree.
+- Migration failure mid-build → the schema state is now ahead of the
+  migration table; inspect before re-running, never loop `migrate:fresh`
+  on shared databases.
+
+### Node / TypeScript
+
+- `tsc` errors that runtime never hits → the types drifted from the
+  code; fix the types, do not add `as any` (the compiler is the only
+  reviewer that reads every call site).
+- Works locally, fails in CI → lockfile drift: CI runs `npm ci` (exact
+  lockfile) while local `npm install` mutated it. Commit the lockfile
+  the build actually needs.
+- `ERR_REQUIRE_ESM` / `Cannot use import` → an ESM-only dependency in a
+  CJS context; align the importing module's format instead of pinning
+  the dependency to a dead major.
+
+### Vue / Nuxt
+
+- Auto-import resolution failures (`X is not defined` only in build) →
+  the dev server tolerates what nitro's build does not; add the
+  explicit import.
+- Hydration-safe code that fails at BUILD time in SSR → browser-only
+  API executed at module top level; move it inside a lifecycle hook or
+  guard it.
+
+### React / Next.js
+
+- Server/client boundary violations (`useState in a Server Component`)
+  → mark the leaf `"use client"`, never the whole tree — pushing the
+  directive up quietly moves the entire subtree to the client bundle.
+- Build-time data fetching failures → a page assumed a runtime env var
+  at static-generation time; decide dynamic vs static explicitly.
+
+### Python
+
+- Import works in the repl, fails in the build → the venv the build
+  uses is not the venv you activated; print `sys.executable` in the
+  failing context before debugging imports.
+- Resolver backtracking forever → over-constrained pins; loosen the
+  pins you own, never the transitive ones.
+- Circular import only at build/collect time → the cycle was always
+  there; imports inside functions defer it, moving the shared symbol
+  out removes it.
+
+## Output
+
+```markdown
+## Build Fix Report
+
+**Failing step:** {command} · **First error:** {file}:{line} — {message}
+**Bucket:** {dependency|config|code|toolchain|cache}
+**Root cause:** {one sentence}
+**Fix:** {what changed and why it addresses the root}
+**Proof:** incremental build exit 0 · clean build exit 0 (commands on record)
+```
+
+A build fixed without the two-build proof, or a symptom silenced with a
+cast or a cache clear, does not close this skill.

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

@@ -0,0 +1,86 @@
+---
+name: dev/react-review
+description: >
+  React / Next.js review for the framework's own traps — stale closures
+  in hooks, dependency arrays that lie, derived state stored instead of
+  computed, keys that force remounts, effects doing render work, and
+  server/client boundary leaks in the App Router — with the fix each
+  needs. Hooks and TypeScript assumed. TRIGGER: "/dev react-review",
+  "review this React", "review the Next.js", "revê este componente
+  React", "revê o hook", "porque é que o efeito corre duas vezes?", any
+  diff touching *.tsx components or custom hooks. SKIP:
+  language-agnostic review -> dev/code-review wins; TypeScript type
+  design without React specifics -> dev/typescript-review wins; a
+  handler-ordering/state-cancellation bug -> dev/click-path-audit wins;
+  visual/brand review -> brand/design-review wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: arkaos
+---
+
+# React Review — `/dev react-review`
+
+> **Agent:** Diana (Senior Frontend Developer) | **Framework:** Hooks semantics, render-cycle discipline, RSC boundaries
+
+Where Vue's traps announce themselves — reactivity silently lost is
+still lost — React's traps ship working code that is wrong later: the
+closure that captured last render's state, the dependency array that
+omits what the effect reads, the memo that never invalidates. This
+review walks the render cycle, not the file: what each render reads,
+what it captures, and what survives to the next one.
+
+## The traps, and the fix each needs
+
+| # | Trap | Signature | Fix |
+|---|------|-----------|-----|
+| 1 | Stale closure | callback reads state captured N renders ago | functional updater (`setX(v => ...)`) or include the dep and let the callback re-create |
+| 2 | Lying dependency array | effect reads `a`, deps say `[b]` | list what the effect READS; if that loops, the effect does too much — split it |
+| 3 | Derived state stored | `useState` mirroring a computable value, synced by effect | compute during render (`useMemo` if costly); delete the effect |
+| 4 | Key-forced remounts | `key={index}` on reorderable lists, or key changing identity every render | stable identity key; component state survives reorders |
+| 5 | Effects doing render work | formatting/filtering in `useEffect` + `setState` | that is render logic — move it into render; effects are for the outside world |
+| 6 | Boundary leak (App Router) | `"use client"` at the top of a tree because one leaf needs a hook | push the directive to the leaf; a client parent drags every child into the bundle |
+| 7 | Context re-render storm | one broad context carrying fast-changing values | split contexts by change rate, memoize the provider value |
+| 8 | Unstable references as props | inline objects/functions into memoized children | hoist or `useCallback`/`useMemo` — or drop the memo, half-memoized is unmemoized |
+
+## Process
+
+For every component and custom hook in scope:
+
+1. **Trace one render**: what it reads, what it computes, what it
+   captures in closures handed to children, effects, or timers.
+2. **Interrogate every `useEffect`**: does it synchronize with an
+   external system (fetch, subscription, DOM)? If it only moves state
+   around, it is a trap-3 or trap-5 candidate.
+3. **Check every dependency array against the closure it feeds** — the
+   array documents what the closure reads; any omission is a latent
+   staleness bug, not an optimization.
+4. **Walk the server/client boundary** (Next.js App Router): where does
+   `"use client"` sit, and does anything serialize a non-serializable
+   prop across it?
+5. **Confirm list keys carry identity**, not position.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- an async callback using state without a functional updater → the
+  stale-closure race it hides
+- `useEffect` + `setState` whose only input is other state → the
+  derived-state rewrite that deletes both
+- a `"use client"` higher than the hook that needs it → the bundle cost
+  and the RSC benefits silently forfeited
+
+## Output
+
+```markdown
+## React Review Report
+
+**Scope:** {components / hooks reviewed}
+
+### {Component / hook} — {file}:{line}
+**Trap:** {#N name} · **Evidence:** {what the render trace shows}
+**Consequence:** {what goes wrong, when}
+**Fix:** {the specific rewrite}
+
+**Verdict:** {clean / N findings, ranked by user impact}
+```

package/departments/ops/skills/hookify/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ops/hookify
+description: >
+  Compiles a repeated correction into a deterministic hook: identify
+  the behavior that keeps being corrected by hand, express it as a
+  machine-checkable predicate, and install it on the right ArkaOS hook
+  surface (PreToolUse deny, Stop lint, UserPromptSubmit nudge) —
+  warn-first with telemetry, hard only when the false-positive rate
+  earns it. TRIGGER: "/ops hookify", "make this automatic", "torna isto
+  automático", "estou farto de corrigir isto", "enforce this rule",
+  "isto devia ser um hook"; the third manual correction of the same
+  behavior. SKIP: capturing a reusable feature build -> arka-recipes
+  wins; automating a business process -> ops/workflow-automate wins;
+  writing an SOP for humans -> ops/sop-create wins.
+allowed-tools: [Read, Grep, Glob, Bash, Write, Edit]
+metadata:
+  origin: arkaos
+---
+
+# Hookify — `/ops hookify`
+
+> **Agent:** Daniel (Operations Lead) | **Framework:** Correction-to-predicate compilation, warn-first enforcement
+
+A hook is a correction that stopped needing you. The third time the
+same behavior gets fixed by hand — the commit message pattern, the file
+that must never be edited directly, the command that needs a flag — the
+correction has stopped being feedback and become a specification
+nobody wrote down. This skill writes it down as executable policy.
+
+## Step 1 — Extract the predicate
+
+From the repeated correction, derive a predicate a machine can decide
+WITHOUT judgment calls:
+
+- **Good**: "Edit on `config/claude-agents/*.md` → deny (generated
+  file; the YAML is the source)."
+- **Not hookifiable**: "commit messages should be clearer" — no
+  decidable predicate. Route vague quality intents to review skills,
+  not hooks; a hook that needs judgment produces false positives that
+  teach the operator to ignore every hook.
+
+State the predicate as: *surface* (which tool calls / which moment),
+*condition* (decidable test), *action* (deny / warn / inject context).
+
+## Step 2 — Pick the surface
+
+| Surface | When it fires | Right for | House examples |
+|---|---|---|---|
+| PreToolUse (`core/hooks/pre_tool_use.py`) | before a tool call | preventing an edit/command that must not happen | frontend gate, research gate |
+| Stop (`core/hooks/stop.py`) | end of turn | measuring compliance, scoped lint over changed files | stop-lint, KB-cite check |
+| UserPromptSubmit (`config/hooks/user-prompt-submit.sh`) | before the turn | nudges and context injection, never blocking | token hygiene checks |
+
+Constraints that are not negotiable: hooks respect their timeout budget
+(UserPromptSubmit 10s, PostToolUse 5s), never block on network, exit 0
+on the non-blocking surfaces, and parse JSON with jq (python3
+fallback). A hook that exceeds its budget degrades every turn to save
+one correction — that trade is always refused.
+
+## Step 3 — Warn first, harden on evidence
+
+New enforcement ALWAYS lands warn-only with telemetry (house pattern:
+the stop-lint and frontend-gate flips). The hook logs would-block
+events to `~/.arkaos/telemetry/`; promotion to hard deny is a separate,
+deliberate change gated on the observed false-positive rate — a gate
+that fires wrongly even 1 turn in 50 gets disabled by hand and trains
+contempt for the ones that fire rightly.
+
+## Step 4 — Install with proof
+
+1. Implement on the chosen surface, following that surface's existing
+   pattern (read the sibling hooks first).
+2. Reproduce the original correction scenario and show the hook
+   catching it — a hook whose trigger was never exercised is a hope,
+   not a control.
+3. Show a benign scenario passing untouched (the false-positive probe).
+4. Register the telemetry line and, if the hook grows a flag, document
+   it where the surface's flags live.
+
+## Output
+
+```markdown
+## Hookify Report
+
+**Correction observed:** {what kept being fixed by hand, with instances}
+**Predicate:** {surface} · {condition} · {action}
+**Mode:** warn-only (telemetry: {file}) · hard-flip criterion: {rate}
+**Proof:** trigger scenario caught ✓ · benign scenario untouched ✓
+**Files:** {hook file, config, telemetry}
+```

package/departments/pm/skills/epic-coordination/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: pm/epic-coordination
+description: >
+  Turns an epic into a coordinated set of GitHub issues with an explicit
+  dependency graph, then drives it: sweep for unblocked work, dispatch
+  in dependency order, keep issue state honest against merged reality,
+  and close the epic only when the graph is empty. TRIGGER: "/pm epic",
+  "break this epic into issues", "parte isto em issues", "coordena
+  estes issues", "what can start now?", "o que está desbloqueado?",
+  multi-PR work spanning more than one workstream. SKIP: sizing and
+  cadence for a sprint -> pm/sprint-plan wins; writing one story well
+  -> pm/story-write wins; branch/merge discipline within a single
+  change -> ops/github-ops wins; ranking the backlog -> pm/backlog-groom
+  wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: arkaos
+---
+
+# Epic Coordination — `/pm epic`
+
+> **Agent:** Carolina (Product Manager) | **Framework:** Dependency-graph decomposition, single-source issue state
+
+An epic dies in one of two ways: as a monolith pull request nobody can
+review, or as twenty issues nobody sequenced — where three developers
+block each other by lunchtime and the "done" column fills with work
+that cannot ship because its dependency never started. Both deaths have
+the same cause: the dependencies existed, but only in someone's head.
+
+## Phase 1 — Decompose against the graph
+
+1. Break the epic into issues where each issue is **independently
+   mergeable**: it can go to master alone without breaking the build,
+   even if the feature is not yet user-visible behind it.
+2. For each issue record what it **blocks** and what it is **blocked
+   by**. A dependency that cannot be named in one sentence ("B reads
+   the schema A creates") is usually a sign the split is wrong — re-cut
+   the boundary before creating anything.
+3. Write the graph INTO the issues (`gh issue create` with "Blocked by
+   #N" / "Blocks #N" in the body, labels for the epic and workstream).
+   GitHub is the single source of state — a graph kept in a document
+   diverges from reality by the second merge.
+
+## Phase 2 — Drive by sweep
+
+Repeat until the graph is empty:
+
+1. **Sweep**: an issue is *unblocked* when every "Blocked by" reference
+   is closed AND its commits are actually on the target branch —
+   closed-but-unmerged is still blocked, whatever the issue state says.
+2. **Dispatch** every unblocked issue; independent issues run in
+   parallel, dependent ones never do.
+3. **Reconcile** after each merge: close what merged, update "Blocked
+   by" lists the merge invalidated, and re-sweep. Reality moves the
+   graph; the graph never moves reality.
+4. **Escalate stalls**: an issue unblocked for longer than the epic's
+   agreed cadence with no movement is a decision waiting to be made —
+   name it to the operator instead of letting the graph silt up.
+
+## Invariants
+
+- Every issue names its epic; the epic issue links every child. Orphan
+  work inside an epic is scope creep with a paper trail.
+- The critical path (longest dependency chain) is stated in the epic
+  issue and re-derived after every reconcile — priorities follow it,
+  not the order issues were created in.
+- Closing the epic requires the graph empty AND the epic's acceptance
+  line verified against the merged state, not against the issue list.
+
+## Output
+
+```markdown
+## Epic Status — {epic title} (#{epic issue})
+
+**Issues:** {open}/{total} · **Critical path:** #{a} → #{b} → #{c}
+**Unblocked now:** #{n}, #{m} · **Blocked:** #{x} (by #{y})
+**Stalled:** {none, or issue + the decision it waits on}
+**Next dispatch:** {what starts now, in what order, and why}
+```

package/harness/codex/AGENTS.md

@@ -0,0 +1,139 @@
+# ArkaOS — The Operating System for AI Agent Teams
+
+> v4.25.0 — 86 agents, 17 departments, 298 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.
+
+## How to work
+
+1. **Route** every request to a department (table below) and say so:
+   `[arka:routing] <dept> -> <lead>`.
+2. **Plan before code.** State the plan and wait for explicit approval
+   on non-trivial work.
+3. **Evidence over narration.** Run the real tests and report the real
+   exit code; a claim about code that was never executed is not a
+   result.
+4. **Quality Gate.** Before delivering, review the work as a critical
+   second reader (copy AND technical) and say honestly what is
+   unfinished. Nothing ships with known defects undisclosed.
+
+## Departments
+
+| Prefix | Lead | Commands |
+|---|---|---|
+| `/dev` | Paulo | 36 |
+| `/mkt` | Luna | 12 |
+| `/brand` | Valentina | 12 |
+| `/fin` | Helena | 10 |
+| `/strat` | Tomas | 10 |
+| `/ecom` | Ricardo | 18 |
+| `/kb` | Clara | 22 |
+| `/ops` | Daniel | 25 |
+| `/pm` | Carolina | 12 |
+| `/saas` | Tiago | 14 |
+| `/landing` | Ines | 14 |
+| `/content` | Rafael | 19 |
+| `/community` | Beatriz | 14 |
+| `/sales` | Miguel | 10 |
+| `/lead` | Rodrigo | 10 |
+| `/org` | Sofia | 10 |
+
+## Agents
+
+Adopt the matching persona when executing department work:
+
+- **brand**: Iris (Design Ops Lead) · Valentina (Creative Director) · Isabel (Visual Designer) · Júlia (UX Strategist) · Leo (Component Library Standardizer) · Mateus (Brand Strategist) · Nia (Design Extraction Engineer) · Oren (Accessibility Auditor) · Renata (UX Researcher) · Sofia D. (UX/UI Designer)
+- **community**: Beatriz (Community Strategist) · Maria (Community Manager) · Tania (Engagement & Gamification Designer)
+- **content**: Rafael (Content Strategist) · Simão (Video Producer & Production Lead) · Dinis (Information Compiler) · Filipe (Viral Content Engineer) · Joana (Scriptwriter) · Madalena (Content Researcher) · Margarida (Trends & Niche Analyst) · Nuno (Repurpose & Distribution Specialist)
+- **dev**: Marco (Chief Technology Officer) · Gabriel (Software Architect) · Paulo (Tech Lead) · Andre (Backend Core Lead) · Bruno (Security Engineer) · Carlos (DevOps Lead) · Diana (Senior Frontend Developer) · Diogo (Python Backend Specialist) · Duarte (Data / ETL Engineer) · Gonçalo (Laravel Specialist) · Rita (QA Engineer) · Salvador (AI Engineering Specialist) · Vasco (Data Platform Lead (Database & Data Engineer)) · Vera (Node.js / TypeScript Backend Specialist) · Maria (Research Assistant)
+- **ecom**: Ricardo (E-Commerce Director) · Alice (CRO Specialist) · Catarina (Lifecycle & Retention Manager) · David (Commerce Engineer)
+- **fin**: Helena (Chief Financial Officer) · Leonor (Financial Analyst) · Rui (Investment & Fundraising Strategist)
+- **kb**: Clara (Knowledge Director) · Francisco (Research Analyst) · Helena C. (Knowledge Curator) · Tomas Jr (Data Collector)
+- **landing**: Ines (Conversion Strategist) · Hugo (CRO Specialist) · Sergio (Affiliate & Partnerships Manager) · Teresa (Sales Copywriter)
+- **lead**: Rodrigo (Leadership & People Director) · Diana R. (HR & Talent Specialist) · Paula (Culture & Performance Coach)
+- **mkt**: Luna (Marketing Director) · Ana (SEO Specialist) · Mariana (Content Marketing Specialist) · Pedro (Performance Marketing Specialist)
+- **ops**: Daniel (Operations Lead) · Tomas A. (Automation Engineer) · Isabel (Documentation Writer)
+- **org**: Sofia (Chief Operations Officer) · Afonso (Chief of Staff & Governance Lead) · Carla (People Operations Specialist) · Matilde (Alignment & OKR Steward) · Pedro M. (Organizational Designer)
+- **pm**: Carolina (Product Manager) · Bárbara (Strategic Program Manager) · Jorge (Scrum Master / Agile Coach) · Sara (Product Owner)
+- **quality**: Eduardo (Copy & Language Director) · Francisca (Technical & UX Quality Director) · Marta (Chief Quality Officer)
+- **saas**: Tiago (SaaS Strategist) · Vicente (RevOps Lead) · Andre S. (Growth Lead) · Patricia (Head of Customer Success) · Rita S. (SaaS Metrics & Voice-of-Customer Analyst)
+- **sales**: Miguel (Sales Director) · Ines S. (Sales Operations Analyst) · Joao (Sales Closer) · Martim (SDR / Pre-Sales)
+- **strat**: Tomas (Chief Strategist) · Guilherme (Decision Quality & Strategic Foresight) · Lucas (Market & Competitive Intelligence Analyst) · Marta S. (Business Model Designer)
+
+## Stack conventions
+
+Apply the section matching the files you touch.
+
+### Laravel Stack Conventions
+
+- Services + Repositories pattern; no logic in controllers.
+- Form Requests for all input validation.
+- API Resources for response shaping.
+- Feature Tests with RefreshDatabase trait.
+- Eloquent relationships over raw joins.
+- Policies for authorization; never inline ability checks.
+- Queued jobs for slow work; never block the request cycle.
+- Conventional commits: `feat(scope): ...`, `fix(scope): ...`.
+
+### Node.js / JavaScript Stack Conventions
+
+- ESM modules (import/export); no CommonJS `require()`.
+- Support Node and Bun runtimes when writing CLI tooling.
+- Graceful fallbacks when optional dependencies are missing.
+- All paths via `os.homedir()` or `path.join`; never hardcoded.
+- No interactive prompts in headless/CI runs.
+- Prefer built-in `node:` modules over dependencies.
+
+### Nuxt Stack Conventions
+
+- Composition API only; no Options API.
+- TypeScript everywhere; no plain JS Vue files.
+- `composables/` for shared reactive logic.
+- `useFetch`/`useAsyncData` for server-side data.
+- `~` alias for project root imports.
+- Server routes in `server/api/`; never fetch third parties from components.
+- Tailwind for styling; avoid scoped styles unless necessary.
+
+### PHP Stack Conventions
+
+- PHP 8.2+ syntax: constructor promotion, readonly, enums, match.
+- `declare(strict_types=1)` in every file.
+- Typed properties, parameters, and return types everywhere.
+- Composer autoload (PSR-4); never `require` project files by path.
+- Exceptions over error returns; never `@` error suppression.
+- Pint (or the project formatter) must pass before a change is done.
+
+### Python Stack Conventions
+
+- Type hints on every function signature.
+- Pydantic for validation; dataclasses for pure data.
+- `pytest` with fixtures; no `unittest.TestCase`.
+- Functions under 30 lines; one responsibility.
+- Docstrings on public API only; self-documenting code elsewhere.
+- Virtual environments; never global `pip install`.
+
+### React / Next.js Stack Conventions
+
+- TypeScript everywhere; no plain JSX files.
+- Server Components by default; `"use client"` only when interaction demands it.
+- App Router (`app/`); no new Pages Router code.
+- shadcn/ui + Tailwind for UI primitives.
+- Hooks for shared logic; no HOC or render-prop patterns in new code.
+- Co-locate component, styles, and test; PascalCase component files.
+
+### Vue Stack Conventions
+
+- Composition API only; no Options API.
+- `<script setup lang="ts">` in every component.
+- Props and emits fully typed (`defineProps`/`defineEmits` generics).
+- Shared reactive logic lives in composables, not mixins.
+- One component per file; PascalCase filenames.
+- v-for always keyed; no index keys on mutable lists.
+
+## Scope of this file
+
+Instruction-level export for this runtime. The full ArkaOS engine —
+context injection, hooks, enforced quality gates, knowledge base — runs
+on runtimes with a native adapter (`npx arkaos install`). This file
+carries the contract so the team behaves like ArkaOS anywhere.