Repository navigation
Description
User Story
As an OpenShell maintainer developing and reviewing repository automation, I need agents organized consistently and reusable runtime support so new agents do not duplicate Gator's execution machinery.
Description
Cover two phases: migrate Gator to the agreed agent layout, then generalize its reusable runtime without coupling all agents to one execution backend.
1. Gator layout migration
Move Gator's bundle to .agents/agents/gator/ with a root run.sh entry point, supporting tools in bin/, and tests in tests/. Retain the existing Gator name, runtime identities, providers, workflow labels, and review policy; descriptive-noun naming applies to new agents.
Update manifests, build contexts, launch references, test tasks, code ownership, repository guidance, and launch-openshell-gator. Keep shared launcher/harness code separate from the bundle. This phase can land independently of runtime generalization.
2. Reusable agent runtime
Build on Gator's existing separation of agent payload, shared OpenShell launcher/supervisor, and harness adapters:
- Preserve agent-owned
run.*entry points and deterministic preflight. Skip model execution when the agent's own rules say no work is needed. - Identify the smallest useful lifecycle/result contract, including completion, waiting, blocking, failure, interruption, and bounded cleanup. Reuse existing contracts where they fit; do not impose watch semantics on one-shot agents.
- Keep execution-specific machinery in backend adapters. OpenShell owns sandbox provisioning, immutable payloads, supervised cycles, and harness execution; CMA-backed agents use the supported SDK for remote sessions and its retry machinery.
- Audit shared code for Gator-specific assumptions, including
GATOR_*defaults and GitHub/Codex requirements, and keep workflow policy in the Gator bundle. - Choose and document a shared runtime location. Extract only demonstrated common behavior; do not require a universal manifest, duplicate SDK session machinery, or force the CMA labeler through Gator's sandbox launcher.
Preserve credential handling, sandbox policy, immutable payload checks, guarded tools, and the independent reviewer boundary throughout both phases.
Context
- feat(review): add labeling agent in Claude Managed Agents #5407 introduces the labeler runtime and agent layout; chore: create an invocable agent for workflow and topic labeling #5276 tracks labeling automation.
- Gator already has shared execution code under
scripts/agents/and agent-owned prompts, skills, providers, and guarded commands. - This work is not a prerequisite for merging the labeler runtime and does not change acceptance or review/disposition policy.
Definition of Done
- Gator layout migration is merged, with affected references and explicit regression suites updated.
- Shared runtime boundaries, location, and invocation/result contracts are documented.
- Reusable execution code is separated from Gator-specific defaults and policy, with regression coverage for the extracted behavior.
- Gator runs through the shared OpenShell backend without changing its policy or security boundaries.
- The pattern accommodates SDK-backed, deterministic-first agents without requiring sandbox execution or a watch loop.
- Follow-up PRs each close their own scoped issue; this tracker stays open until both phases are complete.
Activity
purp commentedon Nov 19, 2026
Phase 1 (#5737): move the existing Gator bundle to
.agents/agents/gator/, retaining its name and runtime identities. Add rootrun.shdelegating to the shared OpenShell launcher; keep shared runtime code inscripts/agents/. Move agent tests totests/and update paths, ownership, operator guidance, and explicit regression commands. Open this migration as a draft PR closing #5737, not this tracker.Phase 2: generalize demonstrated reusable runtime support as described above, separating lifecycle/result contracts and backend execution from Gator policy. Keep CMA SDK-backed execution independent of the OpenShell sandbox backend. No review-policy, provider-permission, credential, or sandbox-policy changes are intended.
[-]refactor(agents): migrate Gator to the contributor agent layout[/-][+]refactor(agents): migrate Gator and generalize reusable runtime support[/+]