InfraKeeper

English | 简体中文

InfraKeeper is an experimental Agent Plugin that packages a standard Agent Skill for evidence-first infrastructure documentation maintenance.

Quick start

1. Install this repository in a compatible Agent Plugin host (see below).
2. Say “初始化 InfraKeeper” or “Set up InfraKeeper”. The Skill opens its read-only setup wizard.
3. Choose GitHub MCP, GitHub CLI (gh), or both. You do not need both backends; one working backend is enough, and adding the second later is supported.
4. Tell the wizard which repository to use (OWNER/REPO). It reports one verdict per backend: ready, unavailable, unauthenticated, insufficient-permissions or unverified.

The wizard is read-only. It never creates a test commit or test file, and it never changes your MCP configuration, environment variables or credential files by itself. You complete OAuth, PAT creation or gh auth login yourself; the Skill never asks for, displays or stores a token.

Setup ends by pointing at a device audit. That audit is not implemented in this version.

Package layout

README.md
README.zh-CN.md
plugin.json
skills/infra-keeper/SKILL.md
skills/infra-keeper/references/
  github-backends.md
  github-mcp.md
  github-cli.md
  github-workflow.md
  setup-wizard.md
docs/hermes.md
tests/
  hermes-smoke-test.md
  hermes-mcp-smoke-test.md
  integration/mcp-lifecycle.md
  integration/cli-lifecycle.md

The plugin packaging is intended for Agent Plugins; the embedded Skill uses the Agent Skills specification. Compatibility must be verified separately per host.

Installation and GitHub access

Install this repository in a compatible Agent Plugin host, or load skills/infra-keeper/ directly in an Agent Skills host. Installing a Skill or Plugin does not authenticate GitHub or install its tool dependencies.

Choose one authorized backend:

• GitHub MCP (preferred): Connect a compatible GitHub MCP server to the Agent host. Official implementation: https://github.com/github/github-mcp-server
• GitHub CLI (gh): For local Agents with shell access, install and authenticate https://cli.github.com/ and verify with gh auth status.

See Hermes Desktop integration notes for the tested setup and limitations.

Safety policy

• Normal documentation changes go directly to main; do not manage branches or PRs.
• Reads, searches, history and status checks may be automatic.
• Every write requires specific prior approval of the proposed path(s), content/diff, impact and rollback.
• Check for concurrent edits before writing; re-read the commit and changed files afterward.
• Do not force-push, rewrite history, change repository administration, or switch backends to bypass a denial.
• Repository documentation is historical evidence, not proof of current service health.
• Never commit credentials, private keys, tokens, or sensitive infrastructure details to public examples.

Verification status (2026-10-22)

Hermes Desktop has successfully loaded the plugin and Skill and completed authenticated read, approval-before-write, and read-back checks through both GitHub CLI and GitHub MCP. The MCP backend has additionally completed a five-stage lifecycle test on main.

Setup wizard status: the wizard protocol is documented and committed, but it has not yet been exercised in an acceptance run. This table reports GitHub access capabilities per backend, not wizard behaviour.

Scope note on the conflict evidence: the stale-version write was rejected on the MCP write path. The returned message does not establish whether the comparison happened in the MCP server or in the GitHub API, so this repository does not claim that GitHub itself enforced version checking on that path. On the CLI backend the stale-SHA write was instead rejected with an HTTP 409 response carrying Server: github.com and a GitHub request ID, so for the REST Contents API this repository does claim server-side enforcement of the sha precondition. The two backends are separate evidence and are not interchangeable.

These were manual, single-environment acceptance tests, not automated conformance tests. The CLI and MCP smoke-test evidence was committed as CLI test 09f4ad2 and MCP test fb31c65; the lifecycle stages are commits 6f336ade, f87b3313, 73fe73b8, b95e8bee and 3be2869d. The CLI lifecycle stages are commits 5d350208, 05a7c7f8, ed63fad4 (web editor), 95b3d34b and 343b25fa; the C-2 rejection produced no commit. ChatGPT/Codex plugin installation has not been separately validated.

Current scope

Only GitHub-backed documentation workflows are implemented. Infrastructure inventory templates, live SSH/cloud operations, reproducible test automation, and full multi-platform validation are future work. A device audit does not exist yet — setup only prepares access to the repository that such an audit would read. Conflict handling has been exercised manually on both backends in separate runs; it is not automated. On the MCP backend the enforcement layer of the stale-version rejection remains unidentified; on the CLI backend it was observed at the GitHub API. No Local Workspace or Local Git backend exists in this version.