arkaos 2.25.0 → 2.28.0

package/VERSION

@@ -1 +1 @@
-2.25.0
+2.28.0

package/arka/skills/bootstrap-agent/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: arka-bootstrap-agent
+description: >
+  Formalises the "agents set up agents" pattern surfaced in the 2026-05-13
+  Nick Saraev × Greg Isenberg podcast on the Orgo agent business. When the
+  user asks to spin up a new specialist or an integration that requires
+  research-heavy setup, this skill orchestrates The Forge to dispatch
+  research subagents (Perplexity / Exa / Context7 / Firecrawl / XMCP),
+  synthesises the findings, and produces a ready-to-use agent YAML or
+  installation guide.
+allowed-tools: [Agent, Read, Write, Bash]
+---
+
+# /arka bootstrap-agent — agents that set up agents
+
+> Pattern source: Nick Saraev (Orgo) interview, 2026-05-13. ArkaOS already
+> has The Forge for complexity-based planning; this skill is the explicit
+> entry point users invoke when they want a new specialist or a setup
+> playbook rather than a feature.
+
+## Subcommands
+
+| Command | What it does |
+| --- | --- |
+| `/arka bootstrap-agent specialist <slug>` | Generates a new Tier 2 agent YAML for a domain you describe. Dispatches research subagents to gather domain frameworks, conventions, and common pitfalls. Produces `departments/<dept>/agents/<slug>.yaml` with full 4-framework DNA. |
+| `/arka bootstrap-agent integration <tool>` | Installation playbook for an external tool (e.g. Hermes, Composio, Agent Mail). Researches official docs + community recipes, outputs a step-by-step setup guide and any required MCP config. |
+| `/arka bootstrap-agent persona <name>` | Builds an AI persona profile (DISC + Enneagram + OCEAN + MBTI) from learned content. Delegates to `/kb` (Clara) for source ingestion. |
+
+## How it works
+
+```
+User: /arka bootstrap-agent specialist "design-tokens-engineer"
+  │
+  ▼
+1. The Forge classifies request complexity (usually "medium" — single
+   specialist, multiple research dimensions).
+2. Spawns 3-5 research subagents in parallel:
+     - Perplexity MCP → real-time framework discovery
+     - Exa AI → semantic search for prior art
+     - Context7 → official documentation pulls
+     - Firecrawl → scrape competitor / canonical sources
+     - XMCP → Twitter / X conversations for community wisdom
+3. Critic synthesis: a Tier 0 reviewer collapses overlap, surfaces
+   contradictions, prioritises by source weight.
+4. Generates the deliverable (YAML / playbook / persona) and saves to
+   the canonical path.
+5. Quality Gate (Marta + Eduardo + Francisca) approves before output
+   reaches the user.
+```
+
+## Why this exists
+
+Per the Orgo interview, the recurring pattern in successful one-person
+agent businesses is "use agents to set up agents". ArkaOS already had
+the primitives — The Forge for planning, the Agent tool for subagent
+dispatch, KB-first research — but no single entry point that made the
+pattern *the* way to add capability. This skill is that entry.
+
+## Boundaries
+
+- This skill **generates**. It does not modify production code.
+- The generated YAML lands in `departments/<dept>/agents/` for review;
+  it is **not** auto-registered until the user commits and the next
+  loader pass picks it up.
+- Personas built via this skill go through `/kb` for the actual
+  content ingestion (YouTube / PDFs / articles). This skill orchestrates,
+  it does not bypass the knowledge pipeline.
+
+## Cross-references
+
+- Source pattern: 2026-05-13 Orgo podcast (Nick Saraev × Greg Isenberg)
+- Related: `/arka forge` (planning engine, lower level)
+- Related: `/kb persona` (content-driven persona builder)
+- Related: `/arka research` (the same research-fan-out pattern for
+  one-off knowledge tasks rather than agent generation)
+- Memory: [[project_next_level_conclave]]

package/arka/skills/design-ops/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: arka-design-ops
+description: >
+  Brand Design Ops sub-squad orchestrator. Routes design-system extraction,
+  WCAG audit, and shadcn padronisation work to Iris (lead) + Nia
+  (extraction) + Oren (WCAG) + Leo (shadcn). Inspired by the AIOX Squad
+  → Sub-Squad pattern documented in the 2026-04-30 KB live and unblocked
+  for ArkaOS by the v2.27.0 Conclave roadmap.
+allowed-tools: [Read, Write, Bash, Edit]
+---
+
+# /brand design-ops — Design Ops sub-squad
+
+> Sub-squad of `/brand` (Valentina). Operational specialists for the
+> production rails of design systems: tokens, audits, components.
+
+## Squad
+
+| Agent | Role | Tier | Owns |
+| --- | --- | --- | --- |
+| **Iris** (`design-ops-lead`) | Lead | 1 | governance, escalation to Valentina |
+| **Nia** (`extraction-script-writer`) | Specialist | 2 | reverse-engineer tokens from sites / figma |
+| **Oren** (`wcag-auditor`) | Specialist | 2 | WCAG 2.2 AA conformance + reports |
+| **Leo** (`shadcn-padronizer`) | Specialist | 2 | shadcn/ui canonical components |
+
+## Subcommands
+
+| Command | Owner | What it does |
+| --- | --- | --- |
+| `/brand design-ops extract <url>` | Nia | Extract color, typography, spacing tokens from a live URL or figma file. Writes JSON to `~/.arkaos/design-ops/<slug>/tokens.json`. |
+| `/brand design-ops wcag <url\|path>` | Oren | Run WCAG 2.2 AA audit. Outputs issue table (severity / criterion / location / fix) + conformance score. |
+| `/brand design-ops shadcn <component>` | Leo | Generate or refactor a component to the shadcn/ui canonical form (CVA variants, Radix primitives, theme tokens). |
+| `/brand design-ops audit <project>` | Iris | Orchestrate full audit: tokens drift, WCAG conformance, component-library variance. Produces a single report. |
+
+## Scripts (under `scripts/`)
+
+The scripts library is intentionally small at v2.27.0 — three reference
+implementations to anchor the pattern. Nia / Oren / Leo extend it as
+ArkaOS evolves; AIOX's reference set is ~30 scripts and ArkaOS will
+catch up incrementally.
+
+| Script | Owner | Input | Output |
+| --- | --- | --- | --- |
+| `scripts/extract-colors.py` | Nia | URL or local HTML | `colors.json` (DTCG-compliant token list) |
+| `scripts/wcag-contrast.py` | Oren | hex pairs OR CSS file | Issue list with contrast ratios + AA / AAA verdict |
+| `scripts/shadcn-tokens.py` | Leo | tokens.json | shadcn CSS variables block + Tailwind config snippet |
+
+Run any script with `python3 scripts/<name>.py --help` for usage.
+
+## Output
+
+All design-ops output writes to:
+- `~/.arkaos/design-ops/<slug>/` — generated artefacts (JSON, CSS, reports)
+- `${VAULT_PATH}/Projects/Design Ops/<slug>.md` — human-readable summary (Obsidian)
+
+## Boundaries
+
+- Strategy and visual direction stay with **Valentina** (`/brand`).
+- Iris escalates anything that requires brand-level taste calls.
+- Design-ops never opens PRs or pushes code; it produces specs, tokens,
+  audits. Implementation goes back to `/dev` via Paulo.
+
+## Cross-references
+
+- Pattern source: KB note `🧠 Knowledge Base/Frameworks/AIOX Squads` (2026-04-30 live)
+- ADR: this skill is the v2.27.0 Conclave instantiation of the sub-squad pattern
+- Parent: `/brand` (Valentina)
+- Stack origin: v2.27.0 (PR5 of 6 from the 2026-05-13 Conclave roadmap)

package/arka/skills/design-ops/scripts/extract-colors.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Extract colour tokens from CSS / HTML / JSON (Nia's reference script).
+
+Scans the input for hex colours and named CSS variables, normalises to
+lower-case 6-digit hex, deduplicates, and emits a DTCG-compliant
+``colors.json`` token list.
+
+Usage:
+    python3 extract-colors.py path/to/styles.css
+    python3 extract-colors.py --stdin < styles.css
+    cat styles.css | python3 extract-colors.py --stdin
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+HEX = re.compile(r"#([0-9a-fA-F]{3,8})\b")
+RGB = re.compile(r"rgb(?:a)?\((\d+)\s*,\s*(\d+)\s*,\s*(\d+)")
+
+
+def normalise(hex_value: str) -> str | None:
+    h = hex_value.lower()
+    if len(h) == 3:
+        h = "".join(c * 2 for c in h)
+    elif len(h) == 4:
+        h = "".join(c * 2 for c in h[:3])
+    elif len(h) == 8:
+        h = h[:6]
+    if len(h) != 6:
+        return None
+    return f"#{h}"
+
+
+def rgb_to_hex(r: int, g: int, b: int) -> str:
+    return f"#{r:02x}{g:02x}{b:02x}"
+
+
+def extract(text: str) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for m in HEX.finditer(text):
+        norm = normalise(m.group(1))
+        if norm and norm not in seen:
+            seen.add(norm)
+            out.append(norm)
+    for r, g, b in RGB.findall(text):
+        norm = rgb_to_hex(int(r), int(g), int(b))
+        if norm not in seen:
+            seen.add(norm)
+            out.append(norm)
+    return out
+
+
+def to_dtcg(colors: list[str]) -> dict:
+    tokens = {}
+    for i, c in enumerate(colors):
+        slug = f"color-{i:03d}"
+        tokens[slug] = {"$value": c, "$type": "color"}
+    return {"$schema": "https://design-tokens.org/draft", "colors": tokens}
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("source", nargs="?", help="path to CSS / HTML file")
+    parser.add_argument("--stdin", action="store_true", help="read from stdin")
+    args = parser.parse_args(argv)
+
+    if args.stdin or args.source == "-":
+        text = sys.stdin.read()
+    elif args.source:
+        text = Path(args.source).read_text(encoding="utf-8")
+    else:
+        parser.error("provide a source path or use --stdin")
+
+    colors = extract(text)
+    print(json.dumps(to_dtcg(colors), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/arka/skills/design-ops/scripts/shadcn-tokens.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Convert DTCG colour tokens into shadcn/ui CSS variables (Leo's script).
+
+Reads a DTCG-style ``colors.json`` (as produced by ``extract-colors.py``)
+and emits the canonical shadcn/ui CSS variable block plus a matching
+``tailwind.config.js`` ``theme.extend.colors`` snippet.
+
+Usage:
+    python3 shadcn-tokens.py colors.json
+    python3 shadcn-tokens.py colors.json --prefix brand-
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def to_css_var(slug: str, value: str, prefix: str) -> str:
+    return f"  --{prefix}{slug}: {value};"
+
+
+def to_tailwind_entry(slug: str, prefix: str) -> str:
+    key = slug.replace("color-", "")
+    return f'        "{prefix}{slug}": "var(--{prefix}{slug})",'
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("source", help="path to DTCG colors.json")
+    parser.add_argument("--prefix", default="", help="CSS variable prefix (e.g. 'brand-')")
+    args = parser.parse_args(argv)
+
+    data = json.loads(Path(args.source).read_text(encoding="utf-8"))
+    tokens = data.get("colors", {})
+    if not tokens:
+        print("no colours found in source", file=sys.stderr)
+        return 1
+
+    css_vars = [to_css_var(slug, t["$value"], args.prefix) for slug, t in tokens.items()]
+    tailwind = [to_tailwind_entry(slug, args.prefix) for slug in tokens]
+
+    print(":root {")
+    print("\n".join(css_vars))
+    print("}\n")
+
+    print("// tailwind.config.js — theme.extend.colors")
+    print("{")
+    print('  theme: { extend: { colors: {')
+    print("\n".join(tailwind))
+    print("  } } }")
+    print("}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/arka/skills/design-ops/scripts/wcag-contrast.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""WCAG 2.2 contrast ratio checker (Oren's reference script).
+
+Compares foreground / background colours and reports whether the pair
+passes WCAG 2.2 Level AA (4.5 : 1 normal text, 3 : 1 large text and UI
+components) and AAA (7 : 1 normal, 4.5 : 1 large).
+
+Usage:
+    python3 wcag-contrast.py "#1a1a1a" "#ffffff"
+    python3 wcag-contrast.py --json "#0f172a" "#ffffff" "#3b82f6" "#ffffff"
+
+Outputs a single-line verdict or, with --json, a structured report.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def relative_luminance(rgb: tuple[int, int, int]) -> float:
+    """WCAG relative luminance formula."""
+    def channel(c: int) -> float:
+        s = c / 255
+        return s / 12.92 if s <= 0.03928 else ((s + 0.055) / 1.055) ** 2.4
+
+    r, g, b = (channel(c) for c in rgb)
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast_ratio(fg: tuple[int, int, int], bg: tuple[int, int, int]) -> float:
+    lf, lb = relative_luminance(fg), relative_luminance(bg)
+    lighter, darker = max(lf, lb), min(lf, lb)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
+    s = hex_color.lstrip("#")
+    if len(s) == 3:
+        s = "".join(c * 2 for c in s)
+    if len(s) != 6:
+        raise ValueError(f"Invalid hex colour: {hex_color}")
+    return int(s[0:2], 16), int(s[2:4], 16), int(s[4:6], 16)
+
+
+def verdict(ratio: float) -> dict[str, bool]:
+    return {
+        "AA_normal": ratio >= 4.5,
+        "AA_large": ratio >= 3.0,
+        "AAA_normal": ratio >= 7.0,
+        "AAA_large": ratio >= 4.5,
+    }
+
+
+def check_pair(fg_hex: str, bg_hex: str) -> dict[str, object]:
+    fg = hex_to_rgb(fg_hex)
+    bg = hex_to_rgb(bg_hex)
+    ratio = round(contrast_ratio(fg, bg), 2)
+    return {
+        "fg": fg_hex,
+        "bg": bg_hex,
+        "ratio": ratio,
+        **verdict(ratio),
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("colors", nargs="*", help="alternating fg bg pairs")
+    parser.add_argument("--json", action="store_true", help="emit JSON report")
+    args = parser.parse_args(argv)
+
+    if len(args.colors) < 2 or len(args.colors) % 2 != 0:
+        parser.error("provide pairs of hex colours: <fg> <bg> [<fg> <bg> ...]")
+
+    pairs = list(zip(args.colors[::2], args.colors[1::2]))
+    results = [check_pair(fg, bg) for fg, bg in pairs]
+
+    if args.json:
+        print(json.dumps({"results": results}, indent=2))
+        return 0
+
+    for r in results:
+        flags = [k for k, v in r.items() if k.startswith("AA") and v]
+        flag_str = "+".join(flags) if flags else "FAILS_ALL"
+        print(f"{r['fg']} on {r['bg']}: {r['ratio']}:1  → {flag_str}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/arka/skills/research/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: arka-research
+description: >
+  Fan-out research workflow. Spawns 5 parallel subagents — Perplexity,
+  Exa AI, Context7, Firecrawl, XMCP — synthesises their findings into
+  a single report, and writes a Knowledge Base note to the Obsidian
+  vault. Inspired by the multi-source research pattern surfaced in the
+  2026-05-13 Orgo podcast (Nick Saraev): "I tell Claude Code, hey,
+  spawn five sub-agents — one for Perplexity, one for Exa, one for
+  Context7, one for Firecrawl, one for XMCP — and we get best practices."
+allowed-tools: [Agent, Read, Write, mcp__obsidian__search_notes]
+---
+
+# /arka research — one prompt, five parallel sources
+
+> Companion to `/arka bootstrap-agent`. Where bootstrap-agent generates
+> capability, this skill generates *knowledge*.
+
+## Usage
+
+```
+/arka research <topic>
+```
+
+`<topic>` is a free-form research question. Examples:
+
+- `/arka research "Hermes agent setup with Telegram gateway"`
+- `/arka research "Mistral Medium 3.5 cost vs Sonnet 4.6"`
+- `/arka research "AIOX Squad de Saúde framework"`
+
+## Sources fanned out
+
+| Subagent | MCP / tool | Strength |
+| --- | --- | --- |
+| Perplexity | `mcp__perplexity__ask` | Real-time web with citations |
+| Exa AI | `mcp__exa__search` | Semantic vector search across the web |
+| Context7 | `mcp__context7__query-docs` | Up-to-date official library docs |
+| Firecrawl | `mcp__firecrawl__firecrawl_scrape` | Site-specific deep scraping |
+| XMCP | `mcp__x__search` | X / Twitter conversations and threads |
+
+If any MCP is not registered in `.mcp.json`, that subagent is skipped
+with a `[arka:source-skipped]` note in the report. KB-first protocol
+still applies — Obsidian search runs before any external call.
+
+## Workflow
+
+```
+1. KB-first: search Obsidian vault for prior notes on the topic.
+   If high-confidence matches exist, the report cites them first
+   and asks the user whether external research is still needed.
+
+2. Fan out 5 subagents in parallel via the Agent tool. Each gets
+   the same topic, returns a focused short brief (≤500 words).
+
+3. Critic synthesis (Tier 0 reviewer, opus): collapses overlap,
+   surfaces contradictions, ranks sources by weight (official docs >
+   recent community threads > older articles).
+
+4. Synthesis report saved to:
+     ${VAULT_PATH}/Knowledge Base/Research/<YYYY-MM-DD>-<slug>.md
+   with full citations and a "where to go next" section.
+
+5. Returns a compact summary to the user (the full report links to
+   the Obsidian note).
+```
+
+## Output shape
+
+```markdown
+---
+title: <topic>
+date: <YYYY-MM-DD>
+sources: [perplexity, exa, context7, firecrawl, xmcp]
+status: synthesised
+tags: [research, <topic-tag>]
+---
+
+# <Topic>
+
+## TL;DR
+<3-bullet summary>
+
+## Findings by source
+### Perplexity
+...
+### Exa AI
+...
+(etc.)
+
+## Synthesis
+<contradictions resolved, ranked by source weight>
+
+## Next steps
+<2-3 follow-up questions or actions>
+```
+
+## Cost & budget
+
+This is a heavy operation — 5 parallel LLM calls plus a synthesis call.
+A typical run consumes 3-8k tokens. The `/arka costs` skill tracks the
+spend and the `[arka:warn]` token-hygiene hook flags excessive use.
+
+## Boundaries
+
+- Read-only: this skill never modifies code or configuration. It only
+  writes to the Obsidian Knowledge Base.
+- KB-first: always check the vault first. Many topics already have
+  notes from prior Dreaming / Research sessions.
+- No external research without the user asking — agents do not
+  proactively fan out unless `/arka research` is invoked.
+
+## Cross-references
+
+- Source pattern: 2026-05-13 Orgo podcast
+- Related: `/arka forge` (planning, not research)
+- Related: `/kb research` (Clara, knowledge management)
+- Related: `/arka bootstrap-agent` (capability-from-research)

package/config/constitution.yaml

@@ -135,6 +135,10 @@ enforcement_levels:
         rule: "All ecosystem skills must follow the standard 7-phase workflow defined in config/standards/ecosystem-workflow.md"
         enforcement: "Ecosystem SKILL.md files must reference or implement all 7 phases"
 
+      - id: sub-squad-hierarchy
+        rule: "Agents in a sub-squad MUST declare parent_squad (department slug) and sub_squad_role. Sub-squads inherit the parent department's authority chain; their lead escalates to the department squad lead, not directly to Tier 0."
+        enforcement: "Agent loader validates parent_squad + sub_squad_role coherence (sub_squad_role requires parent_squad). PR5 v2.27.0 introduced the pattern; AIOX Squad → Sub-Squad → Skills/Scripts is the reference architecture."
+
       - id: forge-persistence
         rule: "All forge plans (approved and rejected) must be persisted to Obsidian"
         enforcement: "persistence.py exports on status change; audit detects missing exports"

package/config/hooks/post-tool-use.sh

@@ -391,6 +391,23 @@ if not match and all_deliverables:
   fi
 fi
 
+# ─── Cognitive layer capture (PR4 v2.26.0 hooks-as-retrieval) ────────────
+# Backgrounded so the hook returns immediately. The retrieval helper has
+# its own internal time caps (ripgrep ≤ 1s, Python fallback capped at 500
+# files) so a runaway extract can never block the next user prompt. We
+# disown so the child cannot zombie if the hook process exits first.
+if [ -n "$SESSION_ID_PTU" ] && [ -n "$TOOL_OUTPUT" ]; then
+  _ARKAOS_REPO=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null || echo "")
+  if [ -n "$_ARKAOS_REPO" ] && [ -d "$_ARKAOS_REPO" ]; then
+    (
+      PYTHONPATH="$_ARKAOS_REPO" python3 -m core.cognition.retrieval capture "$SESSION_ID_PTU" <<EOF >/dev/null 2>&1
+$TOOL_OUTPUT
+EOF
+    ) &
+    disown 2>/dev/null || true
+  fi
+fi
+
 # ─── Log Metrics ─────────────────────────────────────────────────────────
 _DURATION_MS=$(_hook_ms)
 METRICS_FILE="$HOME/.arkaos/hook-metrics.json"

package/config/hooks/user-prompt-submit.sh

@@ -356,9 +356,25 @@ sequential-validation, full-visibility, arka-supremacy."
   fi
 fi
 
+# ─── Cognitive context injection (PR4 v2.26.0 hooks-as-retrieval) ───────
+# Read the context cache populated by the previous PostToolUse turn and
+# inject any KB hits as an `[arka:context]` advisory. The Python helper
+# has internal TTL filtering (10 min) and returns empty when there is no
+# fresh cache, so this stays a no-op until the cognitive layer has data
+# to share.
+_ARKA_CONTEXT_HITS=""
+if [ -n "$SESSION_ID" ]; then
+  _ARKAOS_REPO=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null || echo "")
+  if [ -n "$_ARKAOS_REPO" ] && [ -d "$_ARKAOS_REPO" ]; then
+    _ARKA_CONTEXT_HITS=$(PYTHONPATH="$_ARKAOS_REPO" python3 -m core.cognition.retrieval inject "$SESSION_ID" 2>/dev/null)
+  fi
+fi
+
 # ─── Output ──────────────────────────────────────────────────────────────
 _OUT_CONTEXT="${_ARKA_GREETING:-}${_SYNC_NOTICE:-}${_ROUTE_REMINDER}${_WORKFLOW_DIRECTIVE} $python_result"
 [ -n "$_HYGIENE" ] && _OUT_CONTEXT="$_OUT_CONTEXT $_HYGIENE"
+[ -n "$_ARKA_CONTEXT_HITS" ] && _OUT_CONTEXT="$_OUT_CONTEXT
+$_ARKA_CONTEXT_HITS"
 # Escape for JSON
 _OUT_JSON=$(python3 -c "import json,sys; print(json.dumps(sys.stdin.read()))" <<< "$_OUT_CONTEXT" 2>/dev/null)
 if [ -n "$_OUT_JSON" ]; then

package/core/agents/loader.py

@@ -60,7 +60,10 @@ def load_all_agents(
     for agents_dir in search_dirs:
         if not agents_dir.is_dir():
             continue
-        for yaml_file in sorted(agents_dir.glob("*.yaml")):
+        # Recursive rglob picks up sub-squad subdirectories (e.g.
+        # departments/brand/agents/design-ops/*.yaml) per the v2.27.0
+        # Sub-Squad pattern. Sorted output keeps load order stable.
+        for yaml_file in sorted(agents_dir.rglob("*.yaml")):
             try:
                 agent = load_agent(yaml_file)
                 agents.append(agent)

package/core/agents/schema.py

@@ -273,6 +273,35 @@ class Agent(BaseModel):
         description="Claude model override for dispatch. Falls back to tier default when None.",
     )
 
+    parent_squad: Optional[str] = Field(
+        default=None,
+        description=(
+            "Slug of the parent squad when this agent belongs to a sub-squad. "
+            "Sub-squads are operational specialisations inside a department "
+            "(e.g. brand → design-ops). Optional and backwards-compatible: "
+            "agents without a parent_squad belong directly to their department."
+        ),
+    )
+
+    sub_squad_role: Optional[str] = Field(
+        default=None,
+        description=(
+            "Role within the sub-squad when parent_squad is set "
+            "(e.g. 'lead', 'extraction-script-writer', 'wcag-auditor'). "
+            "Inspired by the AIOX Squad → Sub-Squad pattern (KB note "
+            "AIOX Squads, April 30 2026 live)."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def validate_sub_squad_coherence(self) -> "Agent":
+        """sub_squad_role only makes sense when parent_squad is set."""
+        if self.sub_squad_role and not self.parent_squad:
+            raise ValueError(
+                "sub_squad_role requires parent_squad to be set"
+            )
+        return self
+
     @model_validator(mode="after")
     def auto_fill_memory_path(self) -> "Agent":
         if not self.memory_path: