Sync Agent Infra

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 | update-docs |

| Skills, crates, workflow chains, issue/PR templates, or agent cross-references | sync-agent-infra |

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 — Skill names in the Agent Diagnostic guidance and checklist must exist.
• feature_request.yml — Skill names in the Agent Investigation guidance must exist.
• 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 <label>
- The skill maintenance map has a stale or missing change-area mapping: <details>
- OK: <count> 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>`