sync-agent-infra

name

sync-agent-infra

description

Detect and fix drift across agent-first infrastructure files. Ensures skill inventories, workflow chains, architecture tables, issue/PR templates, and cross-references stay consistent when skills, crates, or workflows change. Run after adding, removing, or renaming skills or components. Trigger keywords - sync agent infra, sync skills, update agent docs, check agent consistency, agent infra drift, sync contributing, sync agents.

Sync Agent Infrastructure

Detect and fix drift across the agent-first infrastructure files. These files reference each other and must stay consistent:

File	What it tracks
AGENTS.md	Project identity, workflow chains, architecture overview, issue/PR conventions, skill maintenance pointer
CONTRIBUTING.md	Skills table, workflow chains, "When to Open an Issue" guidance, skill references
docs/resources/issue-lifecycle.mdx	Human-facing issue states, roadmap decisions, and direct-versus-queued agent ownership
README.md	"Built With Agents" section, "Explore with your agent" skill references
.github/ISSUE_TEMPLATE/bug_report.yml	Skill name references in diagnostic guidance
.github/ISSUE_TEMPLATE/feature_request.yml	Skill name references in investigation guidance
.github/ISSUE_TEMPLATE/config.yml	Contact link text referencing skills
.github/workflows/issue-triage.yml	Comment text referencing skills
.agents/skills/triage-issue/SKILL.md	Skill name references in gate check and diagnosis steps
.agents/skills/openshell-cli/SKILL.md	Companion skills table
.agents/skills/create-github-pr/SKILL.md	Pre-PR agent infrastructure check
.agents/skills/review-github-pr/SKILL.md	Review-time agent infrastructure check
.agents/skills/build-from-issue/SKILL.md	Label awareness and pre-commit agent infrastructure check
.claude/agents/principal-engineer-reviewer.md	Shared review-time agent infrastructure check

When to Run

• After adding, removing, or renaming a skill in .agents/skills/
• After adding, removing, or renaming a crate in crates/
• After changing workflow chain relationships between skills
• After changing which product or development areas a skill covers
• After modifying issue or PR templates
• Before opening a PR that touches any of the above

Skill Maintenance Map

Use this map when product behavior, commands, or development workflows change. It is a routing aid, not an exhaustive dependency list. Search .agents/skills/ for the changed command, field, component, or workflow before concluding that no other skill needs an update.

Change area	Skills to review
CLI commands, flags, defaults, or workflows	openshell-cli
Sandbox policy schema, presets, or enforcement behavior	generate-sandbox-policy, openshell-cli
Supervisor middleware policy, registrations, runtime, or failure behavior	generate-sandbox-policy, openshell-cli, debug-openshell-cluster
Gateway deployment, Helm, runtime drivers, or health checks	debug-openshell-cluster, helm-dev-environment
Inference routing, providers, or inference.local behavior	debug-inference, openshell-cli
TUI architecture, navigation, data fetching, or UX	tui-development
Release artifacts or post-publish smoke coverage	test-release-canary
GitHub Actions workflows, required checks, or CI diagnostics	watch-github-actions; also test-release-canary for release smoke coverage
Gator harness, sandbox image, supervision, or model overrides	launch-openshell-gator
SBOM generation, dependency metadata, or license workflows	sbom
Issue templates, labels, contribution gates, or spike/build workflow	triage-issue, create-spike, build-from-issue, create-github-issue
PR template, review conventions, or vouch behavior	create-github-pr, review-github-pr, build-from-issue
Security review or remediation workflow	review-security-issue, fix-security-issue
RFC template, numbering, or lifecycle	create-rfc
Documentation structure, navigation, or doc-update workflow

Prerequisites

You must be in the OpenShell repository root.

Step 1: Inventory Current State

Gather the source of truth for each category.

Skills

List all skill directories:

ls -1 .agents/skills/

This is the canonical skill list. Every other file must agree with it.

Crates

List all crate directories:

ls -1 crates/

Workflow Chains

The canonical workflow chains are defined in AGENTS.md under "## Workflow Chains". Read that section — it is the source of truth for skill pipelines.

Labels

The canonical label set is used by skills and templates. The key labels are: state:triage-needed, state:needs-info, state:validated, state:accepted, agent:plan-requested, agent:plan-ready, agent:implementation-requested, agent:in-progress, agent:pr-opened, roadmap, topic:security, good first issue, help wanted, spike, and the relevant area:*, topic:*, integration:*, and test:* labels. The agent:* request labels control unattended queue pickup; they are not prerequisites when a user directly asks an agent to work on a specific issue.

Step 2: Check Each File for Drift

For each file in the table above, check for the following inconsistencies:

CONTRIBUTING.md

1. Skills table — Every skill in .agents/skills/ must appear in the "Agent Skills for Contributors" table. No skill in the table should reference a directory that doesn't exist.
2. Workflow chains — Must match AGENTS.md workflow chains exactly.
3. Skill references in prose — Any skill mentioned by name in "Before You Open an Issue", "When to Open an Issue", or "When NOT to Open an Issue" must exist in .agents/skills/.

AGENTS.md

1. Architecture overview — Every crate in crates/ must appear in the architecture table. The python/, proto/, deploy/, .agents/ rows must also be present.
2. Workflow chains — Verify each skill named in a chain exists in .agents/skills/.
3. Issue/PR conventions — Verify referenced skills (create-github-issue, create-github-pr, build-from-issue) exist.
4. Skill maintenance pointer — Verify it still points to sync-agent-infra and does not duplicate the maintenance map from this skill.

Issue Lifecycle Documentation

1. docs/resources/issue-lifecycle.mdx — State, roadmap, and agent-workflow meanings must match AGENTS.md and CONTRIBUTING.md.
2. Invocation modes — The agent:* request labels must control unattended queue pickup without being presented as prerequisites for a direct user request to a specific agent.

README.md

1. "Explore with your agent" — Skill names referenced must exist in .agents/skills/.
2. "Built With Agents" — Skill names referenced must exist. Workflow descriptions should be consistent with AGENTS.md chains.

Issue Templates

1. bug_report.yml — Must collect a User Story, Problem Statement, Impact / Why This Matters, Acceptance Criteria, Reproduction Steps, and Environment. Logs are optional and bug-specific; reporter diagnostics must not be required.
2. feature_request.yml — Must collect a User Story, Problem Statement, Impact / Why This Matters, Proposed Design, Acceptance Criteria, and Alternatives Considered. The design describes workflow and observable behavior without prescribing internal implementation; agent investigation is optional.
3. config.yml — Skill category descriptions in contact links should be accurate.

Issue Triage Workflow

1. issue-triage.yml — Skill names in the redirect comment must exist.

Skill Cross-References

1. triage-issue — Skills referenced in gate check and diagnosis steps must exist.
2. openshell-cli — Companion skills table entries must exist.
3. build-from-issue — Label names must match the project's label taxonomy, and request labels must gate unattended queue pickup without blocking direct user requests.
4. create-spike — Reference to build-from-issue as next step must be accurate.
5. review-security-issue / fix-security-issue — Cross-references between the two must be accurate.
6. PR creation and review checks — The create-github-pr, review-github-pr, build-from-issue, and principal-engineer-reviewer references to sync-agent-infra must exist and use trigger conditions aligned with this skill.

Step 3: Report Drift

If any inconsistencies are found, report them in a structured format:

## Agent Infrastructure Drift Report

### Skills Inventory
- ADDED (exists in .agents/skills/ but missing from CONTRIBUTING.md): <list>
- REMOVED (in CONTRIBUTING.md but missing from .agents/skills/): <list>
- OK: <count> skills consistent

### Architecture Table
- ADDED (exists in crates/ but missing from AGENTS.md): <list>
- REMOVED (in AGENTS.md but missing from crates/): <list>
- OK: <count> components consistent

### Workflow Chains
- STALE: <chain name> references non-existent skill <skill>
- OK: <count> chains consistent

### Cross-References
- <file>:<line> references non-existent skill <skill>
- <file>:<line> references non-existent label <>
 The skill maintenance map has a stale or missing change-area mapping: 
 OK:  references consistent

If no drift is found, report: "Agent infrastructure is consistent. No drift detected."

Step 4: Fix Drift

If drift is found, fix it by updating the affected files:

1. Added skill — Add it to the CONTRIBUTING.md skills table in the appropriate category. If it participates in a workflow chain, update the chains in both AGENTS.md and CONTRIBUTING.md.
2. Removed skill — Remove it from all files. Check for references in templates and other skills.
3. Renamed skill — Update every reference across all files.
4. Added crate — Add a row to the AGENTS.md architecture table.
5. Removed crate — Remove the row from the AGENTS.md architecture table.
6. Changed workflow chain — Update chains in both AGENTS.md and CONTRIBUTING.md. Update the "Built With Agents" section in README.md if the change is user-visible.
7. Changed skill coverage — Update the skill maintenance map in this file and any affected cross-references or companion-skill tables.

After fixing, re-run Step 2 to verify consistency.

Step 5: Summarize Changes

Report what was fixed:

## Changes Made
- Updated CONTRIBUTING.md skills table: added `<skill>`
- Updated AGENTS.md architecture table: removed `<crate>`
- Fixed cross-reference in `.agents/skills/triage-issue/SKILL.md`: `<old>` → `<new>`