CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

jbaruch/herdr-policy

Herdr team coordination policy for AI coding agents

Quality

93%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

session_start_hook.pyskills/herdr-foreman/foreman/

"""Load one bounded role capsule through the shared read-only Herdr role owner.

stdin is the agent's SessionStart JSON (at most 16 KiB). stdout is at most one
agent-native or portable context envelope. Ordinary sessions are silent. No
roster/history scan, cache mutation, binding, admission or dispatch occurs here.
Startup is advisory; failures preserve obligations and never claim authority.
"""

import json
import os
import sys
from pathlib import Path

from . import context_output, role_context
from .errors import ForemanError


INPUT_BYTES = 16_384
ADAPTERS = {"auto", "portable", "claude-code", "codex", "cursor", "grok", "antigravity"}
FAILURE = ("Session-start status — Herdr role context could not be verified. "
           "Preserve existing task ownership, unknown sends and operator holds; "
           "restore the current hook/controller before continuing team work.")


def _adapter(environment):
    adapter = environment.get("HERDR_HOOK_ADAPTER", "auto")
    if adapter not in ADAPTERS:
        raise ValueError("unknown hook adapter")
    if adapter == "auto":
        adapter = "portable" if environment.get("TESSL_AGENT") else "codex"
    return adapter


def _envelope(adapter, context):
    result: dict
    if adapter == "antigravity":
        result = {"injectSteps": [{"systemMessage": {"systemMessage": context}}]}
    elif adapter == "portable":
        result = {"additionalContext": context}
    elif adapter == "cursor":
        result = {"additional_context": context}
    else:
        result = {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": context}}
    return context_output.enforce_budget(result, "Restore a bounded role capsule before Herdr startup.")


def collect(skill, environment, payload=None, *, context_reader=role_context.select):
    """Adapter formatting shares one role check; environment alone proves none."""
    if "HERDR_ENV" not in environment:
        return None
    adapter = _adapter(environment)
    if adapter == "portable" and environment.get("TESSL_AGENT") in ("claude-code", "codex", "antigravity"):
        return None
    try:
        result = context_reader(skill, environment=environment, payload=payload,
                                **role_context.selected_paths(environment))
        context = result["context"]
        if not context:
            return None
        if not isinstance(context, str) or len(context.encode("utf-8")) > role_context.CONTEXT_BYTES:
            raise ValueError("role capsule exceeds its budget")
        context = "Session-start status — Herdr role: {} ({}).\nSkill root: {}\n\n{}".format(
            result["role"], result["reason"], Path(skill).resolve(), context)
        return _envelope(adapter, context)
    except (ForemanError, OSError, ValueError, KeyError, TypeError) as exc:
        # Never emit a partly read contract or an unbounded owner diagnostic.
        print("herdr-session-start: {} — restore the co-shipped hook, role contract and current owner".format(
            type(exc).__name__), file=sys.stderr)
        return _envelope(adapter, FAILURE)


def _input(stream):
    raw = stream.read(INPUT_BYTES + 1)
    raw = raw.encode("utf-8") if isinstance(raw, str) else raw
    if len(raw) > INPUT_BYTES:
        raise ValueError("SessionStart input exceeds 16 KiB")
    payload = json.loads(raw)
    if not isinstance(payload, dict):
        raise ValueError("SessionStart input must be an object")
    return payload


def main():
    if "HERDR_ENV" not in os.environ:
        return 0
    try:
        adapter = _adapter(os.environ)
        if adapter == "portable" and os.environ.get("TESSL_AGENT") in ("claude-code", "codex", "antigravity"):
            return 0
        payload = _input(getattr(sys.stdin, "buffer", sys.stdin))
        result = collect(Path(__file__).resolve().parents[1], os.environ, payload)
    except (ValueError, UnicodeDecodeError) as exc:
        print("herdr-session-start: invalid hook input ({}) — restore the agent's SessionStart payload".format(
            type(exc).__name__), file=sys.stderr)
        return 0
    if result:
        print(json.dumps(result))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

skills

herdr-foreman

foreman

__init__.py

__main__.py

antigravity_native.py

assign.py

attention_view.py

attention.py

billing.py

bootstrap_recovery.py

brief_inputs.py

capabilities.py

chronology.py

churn.py

claude_native.py

cli.py

codex_goals.py

command_context.py

composer.py

composition.py

config.py

context_evidence.py

context_output.py

coordination_metrics.py

cost_report.py

delivery_collection.py

diagnostics.py

engagement.py

errors.py

foreman_queue.py

foreman_reset.py

github_context.py

herdr.py

historical.py

home.py

host_goals.py

launch.py

lifecycle.py

load_set.py

measure.py

measurement_capture.py

measurement_retry.py

members.py

memory.py

model_unavailability.py

native_permissions.py

native_policy.py

no_work_recovery.py

observer_projection.py

observer_role.py

oracle.py

parsers.py

partition.py

plan_explanation.py

planner.py

policy_paths.py

probe_recovery.py

probe.py

process_lease.py

progression_owner.py

progression_runtime.py

progression_service.py

provision.py

recovery.py

release_activation.py

release_checkout.py

release_flight.py

release_rebind.py

remote_owner.py

remote_service.py

renderable.py

report_contract.py

report_delivery.py

report_gates.py

reset_input_hook.py

restoration.py

retrospective_runtime.py

retrospective.py

role_clear.py

role_context.py

runnable.py

selection.py

session_start_hook.py

state.py

successors.py

supervision_gate.py

supervision_hook.py

supervision_runtime.py

supervision.py

task_evidence.py

tier_routing.py

tiers.py

triggers.py

workflow_adoption.py

workflow_artifacts.py

workflow_batch.py

workflow_capacity.py

workflow_contract.py

workflow_dispatch.py

workflow_native.py

workflow_planning.py

workflow_profiles.py

workflow_readiness.py

workflow_recovery.py

workflow_release.py

workflow_rename.py

workflow_review.py

workflow_service.py

workflow_upgrade.py

workflow_workspace.py

antigravity.example.json

bootstrap-repository.py

compose-briefs.sh

config.example.json

foreman-tier-check.py

foreman.sh

label-workspaces.sh

measurements.py

native-hook.sh

observer-view.py

policy-paths.py

prepare-briefs.py

provision-worktree.sh

prune-report-caches.py

resolve-gates.sh

resolve-policy-paths.sh

review-package.sh

roster.sh

round-preflight.sh

SKILL.md

start-judge-worker.sh

state-schema.md

sweep-worktrees.sh

verify-authority.sh

wait-report.sh

workflow-review.py

README.md

tile.json