arkaos 5.1.0 → 5.2.0

package/scripts/skills_catalog_gen.py

@@ -0,0 +1,225 @@
+"""Skills catalog generator — every SKILL.md in the system, one page.
+
+Documents the complete skill surface: 318 department skills plus the 15
+``/arka`` meta skills (333 total). Single source of truth: the SKILL.md
+files themselves (``departments/*/skills/*/SKILL.md`` and
+``arka/skills/*/SKILL.md``), never hand-typed counts. This script
+GENERATES:
+
+- ``docs/SKILLS-CATALOG.md`` — per-department catalog with slug, path,
+  and description for every skill.
+
+Regenerate + commit after touching any SKILL.md set, department
+layout, or VERSION:
+
+    python scripts/skills_catalog_gen.py
+
+``tests/python/test_skills_catalog_gen.py`` drift-gates the committed
+file against a fresh in-memory run, byte for byte.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - venv-only dependency
+    yaml = None
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+OUTPUT = REPO_ROOT / "docs" / "SKILLS-CATALOG.md"
+
+# Canonical department order — mirrors scripts/tools/docs_stats.py
+DEPARTMENT_ORDER = [
+    "dev",
+    "marketing",
+    "brand",
+    "finance",
+    "strategy",
+    "ecom",
+    "kb",
+    "ops",
+    "pm",
+    "saas",
+    "landing",
+    "content",
+    "community",
+    "sales",
+    "leadership",
+    "org",
+]
+
+DEPT_TITLES = {
+    "dev": "Development",
+    "marketing": "Marketing",
+    "brand": "Brand & Design",
+    "finance": "Finance",
+    "strategy": "Strategy",
+    "ecom": "E-Commerce",
+    "kb": "Knowledge",
+    "ops": "Operations",
+    "pm": "Project Management",
+    "saas": "SaaS",
+    "landing": "Landing Pages",
+    "content": "Content",
+    "community": "Communities",
+    "sales": "Sales",
+    "leadership": "Leadership",
+    "org": "Organization",
+}
+
+
+def _clean_description(raw: str | None, fallback: str) -> str:
+    """First sentence(s) of the description, single line, truncated."""
+    if not raw:
+        return fallback
+    text = raw.replace("TRIGGER:", ". TRIGGER:").split("TRIGGER:")[0]
+    text = re.sub(r"\s+", " ", text).strip()
+    text = re.sub(r"\s+\.", ".", text)
+    if len(text) > 180:
+        text = text[:177].rstrip() + "..."
+    return text or fallback
+
+
+def _skill_entry(path: Path) -> dict:
+    """slug, name, description from a SKILL.md frontmatter."""
+    text = path.read_text(encoding="utf-8", errors="replace")
+    name = path.parent.name
+    description = path.stem
+    if yaml is not None and text.startswith("---"):
+        parts = text.split("---", 2)
+        if len(parts) >= 3:
+            try:
+                meta = yaml.safe_load(parts[1]) or {}
+                name = meta.get("name", name)
+                description = _clean_description(meta.get("description"), name)
+            except Exception:
+                pass
+    if description == name:
+        for line in text.splitlines():
+            line = line.strip()
+            if line and not line.startswith("#") and not line.startswith("---"):
+                description = _clean_description(line, name)
+                break
+    return {"slug": path.parent.name, "name": name, "description": description}
+
+
+def _dept_skills() -> dict[str, list[dict]]:
+    """department slug -> hub entry first, then sorted sub-skill entries.
+
+    Matches docs_stats.py semantics: the department hub
+    (``departments/<dept>/SKILL.md``) IS counted as a skill, so the
+    grand total reconciles with the canonical 333 headline.
+    """
+    result: dict[str, list[dict]] = {}
+    for dept_dir in (REPO_ROOT / "departments").iterdir():
+        if not dept_dir.is_dir() or "vendor" in dept_dir.parts:
+            continue
+        entries = []
+        hub = dept_dir / "SKILL.md"
+        if hub.is_file():
+            entry = _skill_entry(hub)
+            entry["slug"] = f"{dept_dir.name}-hub"
+            entry["name"] = f"{dept_dir.name} (hub)"
+            entries.append(entry)
+        skills_dir = dept_dir / "skills"
+        if skills_dir.is_dir():
+            for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
+                if "vendor" in skill_md.parts:
+                    continue
+                entries.append(_skill_entry(skill_md))
+        if entries:
+            result[dept_dir.name] = entries
+    return result
+
+
+def _arka_skills() -> list[dict]:
+    """The 15 /arka meta skills: the master orchestrator plus the 14
+    sub-skills under arka/skills/*/SKILL.md."""
+    master = REPO_ROOT / "arka" / "SKILL.md"
+    entries = []
+    if master.is_file():
+        entry = _skill_entry(master)
+        entry["slug"] = "arka"
+        entry["name"] = "arka (master orchestrator)"
+        entries.append(entry)
+    skills_dir = REPO_ROOT / "arka" / "skills"
+    if skills_dir.is_dir():
+        for skill_md in sorted(skills_dir.glob("*/SKILL.md")):
+            if "vendor" in skill_md.parts:
+                continue
+            entries.append(_skill_entry(skill_md))
+    return entries
+
+
+def generate() -> str:
+    """Return the full SKILLS-CATALOG.md content."""
+    dept_skills = _dept_skills()
+    arka_skills = _arka_skills()
+    dept_total = sum(len(v) for v in dept_skills.values())
+    total = dept_total + len(arka_skills)
+
+    lines = [
+        "# ArkaOS Skills Catalog",
+        "",
+        "> Generated by `scripts/skills_catalog_gen.py`; do not edit. Regenerate after",
+        "> touching any SKILL.md, department layout, or VERSION.",
+        "",
+        f"**{total} skills** — {dept_total} department skills across "
+        f"{len(dept_skills)} departments, plus {len(arka_skills)} `/arka` meta skills.",
+        "",
+        "## Summary",
+        "",
+        "| Department | Skills |",
+        "| --- | --- |",
+    ]
+    for slug in DEPARTMENT_ORDER:
+        if slug in dept_skills:
+            lines.append(f"| {DEPT_TITLES[slug]} (`{slug}`) | {len(dept_skills[slug])} |")
+    for slug in sorted(set(dept_skills) - set(DEPARTMENT_ORDER)):
+        lines.append(f"| {slug} | {len(dept_skills[slug])} |")
+    lines.append(f"| **Total departments** | **{dept_total}** |")
+    lines.append(f"| `/arka` meta skills | {len(arka_skills)} |")
+    lines.append(f"| **Grand total** | **{total}** |")
+    lines.append("")
+
+    lines.append("## Department skills")
+    lines.append("")
+    for slug in DEPARTMENT_ORDER:
+        entries = dept_skills.get(slug)
+        if not entries:
+            continue
+        lines.append(f"### {DEPT_TITLES[slug]} (`{slug}`)")
+        lines.append("")
+        lines.append("| Skill | Name | Description |")
+        lines.append("| --- | --- | --- |")
+        for entry in entries:
+            lines.append(
+                f"| `{entry['slug']}` | {entry['name']} | {entry['description']} |"
+            )
+        lines.append("")
+
+    lines.append("## `/arka` meta skills")
+    lines.append("")
+    lines.append("| Skill | Name | Description |")
+    lines.append("| --- | --- | --- |")
+    for entry in arka_skills:
+        lines.append(
+            f"| `{entry['slug']}` | {entry['name']} | {entry['description']} |"
+        )
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    content = generate()
+    OUTPUT.write_text(content, encoding="utf-8")
+    print(f"skills catalog generated: {OUTPUT.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/workflows_catalog_gen.py

@@ -0,0 +1,161 @@
+"""Workflows catalog generator — every workflow YAML in the system.
+
+Documents the complete workflow surface: the enterprise, focused, and
+specialist workflows defined under ``departments/*/workflows/*.yaml``.
+Single source of truth: the workflow YAML files themselves — never
+hand-typed counts. This script GENERATES:
+
+- ``docs/WORKFLOWS-CATALOG.md`` — per-department workflow reference
+  with tier, command, phase count, gate types, and quality-gate flag.
+
+Regenerate + commit after touching any workflow YAML, department
+layout, or VERSION:
+
+    python scripts/workflows_catalog_gen.py
+
+``tests/python/test_workflows_catalog_gen.py`` drift-gates the
+committed file against a fresh in-memory run, byte for byte.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - venv-only dependency
+    yaml = None
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+OUTPUT = REPO_ROOT / "docs" / "WORKFLOWS-CATALOG.md"
+
+DEPT_TITLES = {
+    "dev": "Development",
+    "marketing": "Marketing",
+    "brand": "Brand & Design",
+    "finance": "Finance",
+    "strategy": "Strategy",
+    "ecom": "E-Commerce",
+    "kb": "Knowledge",
+    "ops": "Operations",
+    "pm": "Project Management",
+    "saas": "SaaS",
+    "landing": "Landing Pages",
+    "content": "Content",
+    "community": "Communities",
+    "sales": "Sales",
+    "leadership": "Leadership",
+    "org": "Organization",
+}
+
+TIER_LABELS = {
+    "enterprise": "Enterprise (7-10 phases, mandatory Quality Gate)",
+    "focused": "Focused (3-4 phases)",
+    "specialist": "Specialist (1-2 phases)",
+}
+
+
+def _workflow_entry(path: Path) -> dict | None:
+    """id, name, description, tier, command, phases, gates from YAML."""
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except Exception:
+        return None
+    if not isinstance(data, dict) or "id" not in data:
+        return None
+    phases = data.get("phases", []) or []
+    gate_types = []
+    for phase in phases:
+        gate = phase.get("gate") if isinstance(phase, dict) else None
+        if isinstance(gate, dict) and gate.get("type"):
+            gate_types.append(str(gate["type"]))
+    return {
+        "id": str(data["id"]),
+        "name": str(data.get("name", data["id"])),
+        "description": str(data.get("description", "")).strip(),
+        "tier": str(data.get("tier", "specialist")),
+        "command": str(data.get("command", "")),
+        "phases": len(phases),
+        "gates": sorted(set(gate_types)),
+        "quality_gate": bool(data.get("quality_gate_required", False)),
+    }
+
+
+def _dept_workflows() -> dict[str, list[dict]]:
+    result: dict[str, list[dict]] = {}
+    for dept_dir in (REPO_ROOT / "departments").iterdir():
+        if not dept_dir.is_dir() or "vendor" in dept_dir.parts:
+            continue
+        wf_dir = dept_dir / "workflows"
+        if not wf_dir.is_dir():
+            continue
+        entries = []
+        for wf_yaml in sorted(wf_dir.glob("*.yaml")):
+            entry = _workflow_entry(wf_yaml)
+            if entry:
+                entries.append(entry)
+        if entries:
+            result[dept_dir.name] = entries
+    return result
+
+
+def generate() -> str:
+    """Return the full WORKFLOWS-CATALOG.md content."""
+    dept_workflows = _dept_workflows()
+    total = sum(len(v) for v in dept_workflows.values())
+    tiers: dict[str, int] = {}
+    for entries in dept_workflows.values():
+        for entry in entries:
+            tiers[entry["tier"]] = tiers.get(entry["tier"], 0) + 1
+
+    lines = [
+        "# ArkaOS Workflows Catalog",
+        "",
+        "> Generated by `scripts/workflows_catalog_gen.py`; do not edit. Regenerate",
+        "> after touching any workflow YAML, department layout, or VERSION.",
+        "",
+        f"**{total} workflows** across {len(dept_workflows)} departments.",
+        "",
+        "## Summary",
+        "",
+        "| Department | Workflows |",
+        "| --- | --- |",
+    ]
+    for slug in sorted(dept_workflows):
+        title = DEPT_TITLES.get(slug, slug)
+        lines.append(f"| {title} (`{slug}`) | {len(dept_workflows[slug])} |")
+    lines.append(f"| **Total** | **{total}** |")
+    lines.append("")
+    lines.append("| Tier | Count |")
+    lines.append("| --- | --- |")
+    for tier in sorted(tiers):
+        lines.append(f"| {TIER_LABELS.get(tier, tier)} | {tiers[tier]} |")
+    lines.append("")
+
+    for slug in sorted(dept_workflows):
+        title = DEPT_TITLES.get(slug, slug)
+        lines.append(f"## {title} (`{slug}`)")
+        lines.append("")
+        lines.append("| Workflow | Tier | Command | Phases | Gates | QG |")
+        lines.append("| --- | --- | --- | --- | --- | --- |")
+        for entry in dept_workflows[slug]:
+            gates = ", ".join(entry["gates"]) if entry["gates"] else "—"
+            qg = "yes" if entry["quality_gate"] else "—"
+            lines.append(
+                f"| `{entry['id']}` | {TIER_LABELS.get(entry['tier'], entry['tier'])} | "
+                f"`{entry['command']}` | {entry['phases']} | {gates} | {qg} |"
+            )
+        lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    content = generate()
+    OUTPUT.write_text(content, encoding="utf-8")
+    print(f"workflows catalog generated: {OUTPUT.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())