| 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
- 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.
- Workflow chains — Must match
AGENTS.md workflow chains exactly.
- 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
- Architecture overview — Every crate in
crates/ must appear in the architecture table. The python/, proto/, deploy/, .agents/ rows must also be present.
- Workflow chains — Verify each skill named in a chain exists in
.agents/skills/.
- Issue/PR conventions — Verify referenced skills (
create-github-issue, create-github-pr, build-from-issue) exist.
- Skill maintenance pointer — Verify it still points to
sync-agent-infra and does not duplicate the maintenance map from this skill.
Issue Lifecycle Documentation
docs/resources/issue-lifecycle.mdx — State, roadmap, and agent-workflow meanings must match AGENTS.md and CONTRIBUTING.md.- 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
- "Explore with your agent" — Skill names referenced must exist in
.agents/skills/.
- "Built With Agents" — Skill names referenced must exist. Workflow descriptions should be consistent with
AGENTS.md chains.
Issue Templates
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.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.config.yml — Skill category descriptions in contact links should be accurate.
Issue Triage Workflow
issue-triage.yml — Skill names in the redirect comment must exist.
Skill Cross-References
triage-issue — Skills referenced in gate check and diagnosis steps must exist.openshell-cli — Companion skills table entries must exist.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.create-spike — Reference to build-from-issue as next step must be accurate.review-security-issue / fix-security-issue — Cross-references between the two must be accurate.- 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:
- 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.
- Removed skill — Remove it from all files. Check for references in templates and other skills.
- Renamed skill — Update every reference across all files.
- Added crate — Add a row to the AGENTS.md architecture table.
- Removed crate — Remove the row from the AGENTS.md architecture table.
- 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.
- 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>`
