workbay-system 0.1.0__tar.gz

workbay_system-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.DS_Store
+DASHBOARD.md

workbay_system-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: workbay-system
+Version: 0.1.0
+Summary: Canonical workbay-system overlay payload (skills, hooks, contracts, generator) shipped as package data for workbay-bootstrap.
+Project-URL: Homepage, https://github.com/darce/workbay
+Project-URL: Source, https://github.com/darce/workbay/tree/main/packages/workbay-system
+Author: darce
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: hatchling>=1.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# workbay-system
+
+Shared workbay-system surface: skills, hooks, contracts, commands, prompts,
+and the validators that keep them coherent.
+
+This repository is **MVP-scope-private** internal tooling. It is consumed by
+the `workbay-bootstrap` CLI, which clones it into
+`<consumer-root>/.workbay/remote/` and symlinks selected surfaces into
+consumer repos. There is no LICENSE or CONTRIBUTING file by design.
+
+## Contents
+
+The canonical sources are model-agnostic. Per-agent surfaces
+(`.claude/skills/`, `.claude/commands/`, `.github/prompts/`,
+`.codex/skills/`, `.cursor/skills/`, `.grok/plugins/workbay-system/`, ...) are
+*generated* into target repos by
+`scripts/generate_agent_workflows.py` during `workbay-bootstrap install`.
+They do not exist in this package's source tree.
+
+| Path                                          | Purpose                                                                 |
+| --------------------------------------------- | ----------------------------------------------------------------------- |
+| `skills/<slug>/skill.yaml`                    | Canonical structured metadata per skill. Validates against `workbay_protocol.SkillManifest`. |
+| `skills/<slug>/body.md`                       | Canonical prose body per skill. Plain Markdown, no frontmatter.         |
+| `config/agent-workflows/portable_commands.json` | Source-of-truth manifest for the portable command router.             |
+| `scripts/generate_agent_workflows.py`         | Renders the manifest + skills into per-agent artifacts (Claude commands + skill packs, Copilot prompts, Codex router blocks, Codex/Cursor/grok skill copies). |
+| `scripts/check_skills.py`                     | Skill-anatomy validator (delegates structured validation to `workbay_protocol.SkillManifest`). |
+| `scripts/check_harness_sync.py`               | Cross-harness contract validator.                                       |
+| `scripts/migrate_skills_to_neutral_layout.py` | One-shot migration helper from the legacy `.claude/skills/<slug>/SKILL.md` layout. |
+| `scripts/hooks/`                              | Claude Code / Copilot shared hooks plus client-side git hooks.          |
+| `docs/workbay/contracts/`                     | YAML contracts (`harness-protocol.yaml` and friends).                   |
+| `docs/workbay/maps/mcp-tool-routing.yaml`     | Routing map consumed by `check_skills.py` to validate `mcp_tools` references. |
+| `docs/plugin-distribution.md`                 | Operator guide for `make plugins-build` / `make plugins-check` and the Claude / Codex / Cursor / grok install flow. See also [ADR-001](docs/workbay/adrs/ADR-001-agentic-plugin-distribution.md). |
+| `Makefile.d/plugins.mk`                       | Make-target fragment wiring `plugins-build` / `plugins-check` to `generate_agent_workflows.py --mode=plugin`. |
+
+## Versioning
+
+This repository uses Semantic Versioning. The current package release is
+`workbay-system 0.4.0`; the current monorepo distribution tag is
+`v0.1.24`. See `CHANGELOG.md` for the full history.
+
+## Provenance
+
+- `v0.2.0` was extracted from a consumer repository snapshot. It expands the skill
+  catalog to 21 populated skills, hoists the
+  `.claude/commands/`, `.github/prompts/`, and
+  `docs/workbay/templates/` surfaces, and splits the
+  `docs/workbay/contracts/` directory so only the six agent/agentic
+  contracts ship in the hoisted surface (the consumer-specific
+  contracts were removed).
+- `v0.1.0` was extracted from the first consumer repository snapshot
+  used to seed this package.
+
+## Consumer Setup
+
+The `workbay-bootstrap` CLI handles the clone + symlink +
+overlay-manifest write cycle for consumers. Consumer repos may publish
+repo-local setup notes that point back to this package.

workbay_system-0.1.0/README.md

@@ -0,0 +1,57 @@
+# workbay-system
+
+Shared workbay-system surface: skills, hooks, contracts, commands, prompts,
+and the validators that keep them coherent.
+
+This repository is **MVP-scope-private** internal tooling. It is consumed by
+the `workbay-bootstrap` CLI, which clones it into
+`<consumer-root>/.workbay/remote/` and symlinks selected surfaces into
+consumer repos. There is no LICENSE or CONTRIBUTING file by design.
+
+## Contents
+
+The canonical sources are model-agnostic. Per-agent surfaces
+(`.claude/skills/`, `.claude/commands/`, `.github/prompts/`,
+`.codex/skills/`, `.cursor/skills/`, `.grok/plugins/workbay-system/`, ...) are
+*generated* into target repos by
+`scripts/generate_agent_workflows.py` during `workbay-bootstrap install`.
+They do not exist in this package's source tree.
+
+| Path                                          | Purpose                                                                 |
+| --------------------------------------------- | ----------------------------------------------------------------------- |
+| `skills/<slug>/skill.yaml`                    | Canonical structured metadata per skill. Validates against `workbay_protocol.SkillManifest`. |
+| `skills/<slug>/body.md`                       | Canonical prose body per skill. Plain Markdown, no frontmatter.         |
+| `config/agent-workflows/portable_commands.json` | Source-of-truth manifest for the portable command router.             |
+| `scripts/generate_agent_workflows.py`         | Renders the manifest + skills into per-agent artifacts (Claude commands + skill packs, Copilot prompts, Codex router blocks, Codex/Cursor/grok skill copies). |
+| `scripts/check_skills.py`                     | Skill-anatomy validator (delegates structured validation to `workbay_protocol.SkillManifest`). |
+| `scripts/check_harness_sync.py`               | Cross-harness contract validator.                                       |
+| `scripts/migrate_skills_to_neutral_layout.py` | One-shot migration helper from the legacy `.claude/skills/<slug>/SKILL.md` layout. |
+| `scripts/hooks/`                              | Claude Code / Copilot shared hooks plus client-side git hooks.          |
+| `docs/workbay/contracts/`                     | YAML contracts (`harness-protocol.yaml` and friends).                   |
+| `docs/workbay/maps/mcp-tool-routing.yaml`     | Routing map consumed by `check_skills.py` to validate `mcp_tools` references. |
+| `docs/plugin-distribution.md`                 | Operator guide for `make plugins-build` / `make plugins-check` and the Claude / Codex / Cursor / grok install flow. See also [ADR-001](docs/workbay/adrs/ADR-001-agentic-plugin-distribution.md). |
+| `Makefile.d/plugins.mk`                       | Make-target fragment wiring `plugins-build` / `plugins-check` to `generate_agent_workflows.py --mode=plugin`. |
+
+## Versioning
+
+This repository uses Semantic Versioning. The current package release is
+`workbay-system 0.4.0`; the current monorepo distribution tag is
+`v0.1.24`. See `CHANGELOG.md` for the full history.
+
+## Provenance
+
+- `v0.2.0` was extracted from a consumer repository snapshot. It expands the skill
+  catalog to 21 populated skills, hoists the
+  `.claude/commands/`, `.github/prompts/`, and
+  `docs/workbay/templates/` surfaces, and splits the
+  `docs/workbay/contracts/` directory so only the six agent/agentic
+  contracts ship in the hoisted surface (the consumer-specific
+  contracts were removed).
+- `v0.1.0` was extracted from the first consumer repository snapshot
+  used to seed this package.
+
+## Consumer Setup
+
+The `workbay-bootstrap` CLI handles the clone + symlink +
+overlay-manifest write cycle for consumers. Consumer repos may publish
+repo-local setup notes that point back to this package.

workbay_system-0.1.0/_scrub_core.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Build-time vendor of scripts/_scrub_core.py for hatch builds from sdist."""
+
+from __future__ import annotations
+
+import re
+
+INTERNAL_REF_PREFIXES = (
+    "AHMCP",
+    "AOMCP",
+    "APD",
+    "DCMCP",
+    "WBF",
+    "CHC",
+    "PA",
+    "MAINT",
+    "APM-SPEC-TR",
+    "WORKSTATE-REF",
+)
+
+INTERNAL_REF_RE = re.compile(
+    r"(?<![A-Za-z])(?:"
+    + "|".join(re.escape(prefix) for prefix in INTERNAL_REF_PREFIXES)
+    + r"|WS|WB|E[0-9]+)(?:[0-9]+)?(?:-[A-Z0-9]+)+"
+)
+
+PROCESS_REF_RES = (
+    re.compile(r"\b[Pp]lan\s+[0-9]{4}\b"),
+    re.compile(r"\b[Ss]lice\s+[0-9]+[A-Za-z]?\b"),
+    re.compile(r"\b[Ss]tep\s+[0-9]+/[0-9]+\b"),
+)
+
+INLINE_INTERNAL_PREFIX_RE = re.compile(
+    r"(?<![A-Za-z])(?:AHMCP|AOMCP|APD|DCMCP|WBF|CHC|APM-SPEC-TR)(?![A-Za-z])",
+    re.IGNORECASE,
+)
+
+INLINE_EPIC_REF_RE = re.compile(r"E([0-9]+)-([0-9]+(?:-[A-Z0-9]+)*)")
+
+_COLLAPSE_RE = re.compile(
+    r"\b(?:internal|implementation note)(?:[ \t]+(?:internal|implementation note))+\b"
+)
+
+
+def scrub_text(text: str) -> str:
+    scrubbed = INTERNAL_REF_RE.sub("internal", text)
+    scrubbed = INLINE_INTERNAL_PREFIX_RE.sub("internal", scrubbed)
+    scrubbed = INLINE_EPIC_REF_RE.sub("internal", scrubbed)
+    for regex in PROCESS_REF_RES:
+        scrubbed = regex.sub("implementation note", scrubbed)
+    return _COLLAPSE_RE.sub("internal", scrubbed)

workbay_system-0.1.0/hatch_build.py

@@ -0,0 +1,288 @@
+"""Hatch build hook: scrub staged package copies into wheel+sdist artifacts."""
+
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any, NamedTuple, Protocol
+
+try:  # hatchling is a build-time-only dep (build-system.requires), not a test dep.
+    from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+    from hatchling.metadata.plugin.interface import MetadataHookInterface
+    from hatchling.plugin import hookimpl
+except ModuleNotFoundError:  # keep pure discover_scrub_targets importable for tests
+    BuildHookInterface = object  # type: ignore[assignment,misc]
+    MetadataHookInterface = object  # type: ignore[assignment,misc]
+
+    def hookimpl(func):  # type: ignore[no-redef]
+        return func
+
+_TEXT_SUFFIXES = {
+    ".md",
+    ".py",
+    ".yaml",
+    ".yml",
+    ".json",
+    ".toml",
+    ".txt",
+    ".mk",
+    ".sh",
+    ".in",
+    ".cfg",
+    ".ini",
+    ".template",
+    ".j2",
+}
+
+# Build-support files vendored into the sdist so the wheel can be rebuilt from it.
+# They carry the scrub matcher vocabulary verbatim (the literal AHMCP/AOMCP/... ids
+# the transform looks for) and MUST NOT themselves be scrubbed — doing so rewrites
+# those literals to "internal" and ships a gutted scrub engine. They ride into the
+# sdist via hatchling's own only-include and are scan-exempt in the privacy gate
+# (scripts/check_shipped_privacy.py: _SCAN_EXEMPT_RELPATHS), so skip them here.
+_BUILD_SUPPORT_NAMES = {"_scrub_core.py", "hatch_build.py"}
+
+
+class ScrubTarget(NamedTuple):
+    source_path: Path
+    wheel_prefix: str
+    is_dir: bool
+
+
+class _WheelConfigView(Protocol):
+    packages: list[str] | None
+    only_include: list[str] | None
+    sources: list[str] | None
+
+
+def _strip_src_prefix(path: str) -> str:
+    if path.startswith("src/"):
+        return path.removeprefix("src/")
+    return path
+
+
+def _rel_entry(entry: str, *, root: Path) -> str:
+    entry_path = Path(entry)
+    if entry_path.is_absolute():
+        return entry_path.relative_to(root).as_posix()
+    return entry.replace("\\", "/")
+
+
+def _wheel_prefix_for_entry(entry: str, *, root: Path) -> str:
+    rel = _rel_entry(entry, root=root)
+    if rel.endswith(".py"):
+        return Path(rel).name
+    return _strip_src_prefix(rel.rstrip("/"))
+
+
+def discover_scrub_targets(
+    build_config: _WheelConfigView | Any,
+    *,
+    root: Path,
+) -> list[ScrubTarget]:
+    """Resolve layout-aware scrub targets from the wheel build config."""
+    packages = list(getattr(build_config, "packages", None) or [])
+    only_include = list(getattr(build_config, "only_include", None) or [])
+    sources = list(getattr(build_config, "sources", None) or [])
+
+    targets: list[ScrubTarget] = []
+    covered_sources: set[Path] = set()
+
+    def _append_target(source_path: Path, wheel_prefix: str) -> None:
+        resolved = source_path.resolve()
+        if resolved in covered_sources:
+            return
+        if not source_path.exists():
+            raise FileNotFoundError(source_path)
+        covered_sources.add(resolved)
+        targets.append(
+            ScrubTarget(
+                source_path=source_path,
+                wheel_prefix=wheel_prefix,
+                is_dir=source_path.is_dir(),
+            )
+        )
+
+    package_prefixes = {
+        _strip_src_prefix(_rel_entry(package, root=root).rstrip("/")) for package in packages
+    }
+
+    for package in packages:
+        rel = _rel_entry(package, root=root)
+        _append_target(root / rel, _strip_src_prefix(rel.rstrip("/")))
+
+    for entry in only_include:
+        rel = _rel_entry(entry, root=root)
+        if Path(rel).name in _BUILD_SUPPORT_NAMES:
+            # Vendored build machinery ships verbatim; never stage/scrub it.
+            continue
+        wheel_prefix = _wheel_prefix_for_entry(entry, root=root)
+        if rel.endswith(".py"):
+            source_path = root / rel
+            if not source_path.exists():
+                source_path = root / "src" / Path(rel).name
+        elif wheel_prefix in package_prefixes:
+            source_path = root / rel
+        else:
+            # Root-layout only-include names map to on-disk src/<pkg> trees.
+            candidate = root / "src" / wheel_prefix
+            source_path = candidate if candidate.exists() else root / rel
+        _append_target(source_path, wheel_prefix)
+
+    if targets:
+        return targets
+
+    if sources:
+        for source_root in sources:
+            rel = _rel_entry(source_root, root=root)
+            source_path = root / rel
+            if not source_path.exists():
+                raise FileNotFoundError(source_path)
+            wheel_prefix = _strip_src_prefix(rel.rstrip("/"))
+            targets.append(
+                ScrubTarget(
+                    source_path=source_path,
+                    wheel_prefix=wheel_prefix,
+                    is_dir=source_path.is_dir(),
+                )
+            )
+        return targets
+
+    return targets
+
+
+def _load_scrub_text():
+    scrub_core = Path(__file__).resolve().parent / "_scrub_core.py"
+    spec = importlib.util.spec_from_file_location("scrub_core_build", scrub_core)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.scrub_text
+
+
+def _should_scrub(path: Path) -> bool:
+    return path.suffix.lower() in _TEXT_SUFFIXES or path.name in {
+        "Makefile",
+        "LICENSE",
+        "README.md",
+    }
+
+
+def _scrub_tree(tree: Path, scrub_text) -> None:
+    for path in tree.rglob("*"):
+        if not path.is_file() or path.is_symlink():
+            continue
+        if not _should_scrub(path):
+            continue
+        try:
+            original = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        scrubbed = scrub_text(original)
+        if scrubbed != original:
+            path.write_text(scrubbed, encoding="utf-8")
+
+
+def _stage_target(staging: Path, target: ScrubTarget, scrub_text) -> Path:
+    if target.is_dir:
+        staged = staging / target.wheel_prefix
+        # Drop compiled bytecode/caches: force_include bypasses the sdist `exclude`
+        # globs, so an uncleaned source tree would otherwise ship unscanned .pyc.
+        shutil.copytree(
+            target.source_path,
+            staged,
+            ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"),
+        )
+        _scrub_tree(staged, scrub_text)
+        return staged
+
+    staged = staging / target.wheel_prefix
+    staged.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(target.source_path, staged)
+    if _should_scrub(staged):
+        original = staged.read_text(encoding="utf-8")
+        scrubbed = scrub_text(original)
+        if scrubbed != original:
+            staged.write_text(scrubbed, encoding="utf-8")
+    return staged
+
+
+def _force_include_staged(
+    force_include: dict[str, str],
+    staged_root: Path,
+    wheel_prefix: str,
+) -> None:
+    for path in staged_root.rglob("*"):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(staged_root).as_posix()
+        force_include[str(path)] = f"{wheel_prefix}/{rel}" if rel else wheel_prefix
+
+
+class ScrubAtBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    @property
+    def _staging_dirs(self) -> list[Path]:
+        dirs = getattr(self, "_staging_dirs_store", None)
+        if dirs is None:
+            dirs = []
+            self._staging_dirs_store = dirs
+        return dirs
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        scrub_text = _load_scrub_text()
+        root = Path(self.root)
+        targets = discover_scrub_targets(self.build_config, root=root)
+        if not targets:
+            return
+
+        staging = Path(tempfile.mkdtemp(prefix="workbay-scrub-stage-", dir=None))
+        if not staging.is_absolute():
+            staging = staging.resolve()
+        self._staging_dirs.append(staging)
+        force_include = build_data.setdefault("force_include", {})
+
+        for target in targets:
+            staged = _stage_target(staging, target, scrub_text)
+            if target.is_dir:
+                _force_include_staged(force_include, staged, target.wheel_prefix)
+            else:
+                force_include[str(staged)] = target.wheel_prefix
+
+    def finalize(self, version: str, build_data: dict, artifact_path: str) -> None:
+        while self._staging_dirs:
+            shutil.rmtree(self._staging_dirs.pop(), ignore_errors=True)
+
+
+class ScrubMetadataHook(MetadataHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def update(self, metadata: dict) -> None:
+        """Scrub the README long-description hatchling bakes into core metadata.
+
+        hatchling resolves ``readme`` -> the Description in wheel METADATA / sdist
+        PKG-INFO straight from the authored README, OUTSIDE the build hook's
+        force_include payload, so internal refs there would ship unscrubbed. A
+        package opts in by declaring ``dynamic = ["readme"]`` (and dropping the
+        static ``readme`` key); we supply the scrubbed long-description here.
+        """
+        scrub_text = _load_scrub_text()
+        readme_path = Path(self.root) / "README.md"
+        if readme_path.is_file():
+            metadata["readme"] = {
+                "content-type": "text/markdown",
+                "text": scrub_text(readme_path.read_text(encoding="utf-8")),
+            }
+
+
+@hookimpl
+def hatch_register_build_hook():
+    return ScrubAtBuildHook
+
+
+@hookimpl
+def hatch_register_metadata_hook():
+    return ScrubMetadataHook

workbay_system-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "workbay-system"
+version = "0.1.0"
+description = "Canonical workbay-system overlay payload (skills, hooks, contracts, generator) shipped as package data for workbay-bootstrap."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "darce" }]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/darce/workbay"
+Source = "https://github.com/darce/workbay/tree/main/packages/workbay-system"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pyyaml>=6", "hatchling>=1.27"]
+
+# uv-only dev provisioning: sibling test deps resolve via path-editable sources.
+# ``[project.optional-dependencies] dev`` stays for pip; ``dependency-groups`` is
+# what ``uv sync`` installs by default (also additively with ``--extra dev``).
+# The three shared pins are duplicated in ``[project.optional-dependencies] dev``
+# above (pip path vs uv path) — keep both lists in sync when bumping a pin.
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pyyaml>=6",
+    "hatchling>=1.27",
+    "mcp-workbay-handoff[test] ; python_version >= '3.12'",
+]
+
+[tool.uv.sources]
+mcp-workbay-handoff = { path = "../mcp-workbay-handoff", editable = true }
+workbay-protocol = { path = "../workbay-protocol", editable = true }
+
+# Overlay packaging (0020 S3): the overlay payload is co-located under
+# `workbay_system/payload/` and ships by "ship the package" — `only-include`
+# delivers the importable package (with its payload subtree) and there is no
+# force-include map. Internal-only material (evals, adrs, generated, tests)
+# lives OUTSIDE `workbay_system/`, so it is structurally impossible to sweep
+# into the wheel; `tests/test_payload_colocation.py` (the negative privacy
+# guard + the wheel-vs-source byte-parity test) is the comprehensive guard that
+# no internal file leaks and no needed surface is dropped.
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["workbay_system"]
+exclude = ["**/__pycache__", "**/*.pyc"]
+
+# Source-model rework (0038): the sdist is an allowlist (not a denylist) so
+# internal-only top-level material (task docs, specs, adrs, harness prompts,
+# editor config, dev scripts, agent guides, changelog) can never silently leak
+# into the published source distribution. Ship only what is needed to rebuild
+# the wheel from sdist: the importable package (with its scrubbed payload), the
+# build hook, and its vendored scrub core. pyproject.toml and README.md are
+# always included by hatchling as sdist metadata. The privacy gate scans the
+# *entire* unpacked sdist, so anything added here is also gated.
+[tool.hatch.build.targets.sdist]
+only-include = ["workbay_system", "hatch_build.py", "_scrub_core.py"]
+exclude = ["**/__pycache__", "**/*.pyc", "**/evals/**", "**/evals.mk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = [
+    "integration: uv-driven environment provisioning checks (need `uv`; isolated, side-effect-free).",
+]

workbay_system-0.1.0/workbay_system/__init__.py

@@ -0,0 +1,25 @@
+"""workbay-system overlay payload package.
+
+Ships the canonical overlay surfaces — skills, the workflow generator,
+agent-workflows config, and the shared hook/contract surfaces — as package
+data so ``workbay-bootstrap`` can materialize them from an installed
+distribution (the package delivery source) instead of a git clone.
+
+The payload is co-located under ``workbay_system/payload/`` and ships by
+"ship the package" (``only-include = ["workbay_system"]`` in
+``pyproject.toml`` — no force-include map), so :func:`data_root` resolves to the
+``payload/`` directory that contains ``skills/``, ``scripts/``, ``config/``,
+``docs/``, ``Makefile.d/``, and ``.github/`` once installed.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+__all__ = ["data_root"]
+
+
+def data_root() -> Path:
+    """Return the filesystem root of the installed overlay payload."""
+    return Path(str(resources.files(__name__) / "payload"))

workbay_system-0.1.0/workbay_system/payload/.claude/hooks/ensure-agent-surfaces.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# SessionStart hook — ensure this clone's GENERATED agent surfaces exist.
+#
+# Three agent surfaces are generated into GITIGNORED paths, so a fresh clone
+# carries the pins/sources but not the generated output — and the surfaces
+# silently fail to load until they are built:
+#   - Claude plugin tree  .workbay/generated/plugins/workbay-system/base/claude  (make plugins-build)
+#   - Codex  plugin tree  .workbay/generated/plugins/workbay-system/base/codex   (make plugins-build)
+#   - VS Code Copilot      .github/prompts/                                       (make generate-agent-workflows)
+#
+# This hook regenerates all of them when missing. It can only run on CLAUDE CODE
+# session start — Codex and VS Code Copilot have no equivalent trigger (see the
+# README "Developing in this repo" section) — but because `plugins-build` emits
+# BOTH plugin trees and `generate-agent-workflows` emits the Copilot prompts,
+# opening Claude once bootstraps every surface. Plugins load only at session
+# start, so a one-time restart is needed after the first build. The hook is a
+# no-op (fast, silent) once the surfaces exist and never blocks session start.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+claude_manifest="$repo_root/.workbay/generated/plugins/workbay-system/base/claude/.claude-plugin/plugin.json"
+codex_manifest="$repo_root/.workbay/generated/plugins/workbay-system/base/codex/.codex-plugin/plugin.json"
+copilot_prompts="$repo_root/.github/prompts"
+
+# All three surfaces must be present to skip; checking only Claude + Copilot
+# would leave a partial-drift clone (e.g. only the codex tree deleted) unhealed.
+if [ -f "$claude_manifest" ] && [ -f "$codex_manifest" ] && [ -d "$copilot_prompts" ]; then
+  exit 0
+fi
+
+echo "workbay-system agent surfaces missing (fresh clone?) — generating them…"
+ok=1
+make -C "$repo_root" plugins-build >/dev/null 2>&1 || ok=0
+# Pass WORKFLOW_TARGET_ROOT so the Copilot prompts land in this repo's root
+# .github/prompts/ (the surface VS Code reads); without --target the generator
+# only rewrites the tracked package-level source copy.
+make -C "$repo_root" generate-agent-workflows WORKFLOW_TARGET_ROOT="$repo_root" >/dev/null 2>&1 || ok=0
+if [ "$ok" -eq 1 ]; then
+  echo "Generated the Claude + Codex plugin trees and the VS Code Copilot prompts."
+  echo "RESTART Claude Code (/exit, then reopen) to load the /branch-review, /plan-analyze, … slash commands."
+else
+  echo "Could not auto-generate every surface. Run 'cd \"$repo_root\" && make plugins-build && make generate-agent-workflows WORKFLOW_TARGET_ROOT=\"\$PWD\"' (or 'workbay-bootstrap install --target \"$repo_root\"') manually, then restart Claude Code."
+fi
+exit 0