---
name: sync-agent-infra
description: Reconcile contributor skills, AGENTS.md, CONTRIBUTING.md, issue and PR templates, and workflow references after repository workflow changes.
metadata:
  internal: true
---

# Sync Agent Infrastructure

Keep contributor guidance consistent without copying procedural workflows into `AGENTS.md`. That file holds repository coding conventions and pointers; the relevant skills hold issue, PR, and maintenance procedures. `CONTRIBUTING.md` explains the human workflow.

## When to run

Run after adding, removing, or renaming a skill or crate; changing issue or PR conventions; changing development workflows; or modifying templates or agent cross references. Run before opening a PR that touches these areas.

## Maintenance map

| Change | Skills to inspect |
|---|---|
| Issues, triage, labels, or feature proposals | `create-github-issue`, `triage-issue`, `label-issue`, `review-triage-queue`, `apply-triage-action`, `create-spike`, `build-from-issue` |
| PR template, vouch behavior, or review conventions | `create-github-pr`, `review-github-pr`, `build-from-issue` |
| Security reports, advisories, assessment, or remediation | `create-security-advisory`, `review-security-issue`, `fix-security-issue` |
| Published docs workflow | `update-docs-from-commits` |
| CLI commands, flags, defaults, or workflows | `openshell-cli` |
| Sandbox policy schema or enforcement | `generate-sandbox-policy`, `openshell-cli` |
| Gateway deployment, Helm, drivers, or health checks | `debug-openshell-cluster`, `helm-dev-environment` |
| Inference providers or native model endpoints | `debug-inference`, `openshell-cli` |
| TUI behavior | `tui-development` |
| Release artifacts or smoke coverage | `test-release-canary` |
| Release cadence, tagging, or qualification workflows | `release-captain` |
| Release workflows or publishers | `release-openshell`, `release-captain`; keep the Release workflows table and the manual-trigger rule in `CI.md` current |
| CI diagnostics | `watch-github-actions` |
| Native Windows builds, runtime, or release branch guidance | `build-openshell-mxc-windows`; keep Windows implementation links on `windows` even in docs merged to `main` |
| Gator supervision | `launch-openshell-gator` |
| SBOM workflow | `sbom` |
| RFC workflow | `create-rfc` |

Search both `skills/` and `.agents/skills/` for affected commands, fields, and components; the map is a starting point.

## Consistency check

1. Compare `skills/*/SKILL.md` and `.agents/skills/*/SKILL.md` with the inventories in `CONTRIBUTING.md`. Public skills must work outside a checkout and use installed CLI help and published documentation. Contributor skills must set `metadata.internal: true`. Confirm names are unique and local links resolve.
2. Compare `crates/` with the architecture table in `AGENTS.md`. Check the public and contributor skill rows.
3. Check issue guidance against [Label Discovery](../../../CONTRIBUTING.md#label-discovery), [accepted work](../../../CONTRIBUTING.md#accepted-work), and [`label-issue`](../label-issue/SKILL.md). Preserve caller confirmation rules and phase authorization. Skills use `state:*` definitions without duplicating the label inventory or depending on `agent:*` labels.
4. Check issue templates, `create-github-issue`, `create-spike`, and `triage-issue` for the first-hand OpenShell User Story, OpenShell-only bug reproduction, notional UX examples, and consideration of applicable extension points.
5. Check the PR template, `create-github-pr`, `build-from-issue`, `fix-security-issue`, and `CONTRIBUTING.md`: every PR must close an existing issue covering its scope, except automated dependency updates and build or flaky-test fixes from authors with write access, as described in `CONTRIBUTING.md`. Multi-PR work needs an issue per PR; a separate issue may track the overall effort.
6. Check contributor branch instructions and examples against Branch Names in `CONTRIBUTING.md`; AGENTS.md and skills should refer to that convention. Check `README.md`, `.github/ISSUE_TEMPLATE/`, `.github/workflows/`, `.agents/agents/`, and related skill cross references for stale workflow statements. Keep user-facing documentation changes minimal and avoid duplicated internal explanations.
7. Check that PR, build, TUI, and docs contribution guidance follow the scoped verification guidance in `CONTRIBUTING.md`; they must not require full Rust, SDK, or repository CI for changes that cannot affect those areas.
8. Use `npx -y skills add . --list` from a disposable clean copy when skill discovery changes. It should expose public skills only; clean generated files afterward.

Fix contradictions, then repeat the affected checks. Report files changed and any remaining drift. Do not treat an old document's label list as a source of truth over current GitHub metadata.
