Githits Plugin Maintenance

Maintain GitHits Plugin Surfaces

This is an internal, repository-only skill. Do not publish or package it with the public skills under skills/.

Keep root skills and shared metadata canonical. Treat generated manifests and host MCP files as reviewable build artifacts, not authoring locations.

Workflow

1. Identify the canonical input that owns the requested behavior.
2. Read docs/implementation/plugin-packaging.md before changing packaging or transport behavior.
3. Edit canonical inputs only.
4. For the stable MCP quick-start guide, keep packages/mcp/src/mcp/instructions.ts buildMcpQuickStart() and the terminal ## Quick-start guide section in skills/githits-mcp/SKILL.md byte-for-byte aligned in the same PR. src/skills-packaging.test.ts is the exact-parity contract; exclude buildLocalMcpQuickStart() runtime appendices from the public copy. Route behavior-dependent guide changes through the public Agent Skill lifecycle.
5. Run bun run plugins:generate.
6. Inspect every generated diff and confirm it follows from the canonical change.
7. Run bun run plugins:check.
8. Run targeted tests, then the required smoke or agent evaluations for the affected surface.

Canonical Ownership

• Author public skill content only under skills/.
• Author shared agent guidance in AGENTS.md; keep CLAUDE.md and GEMINI.md as symlinks to it.
• packages/mcp/src/mcp/instructions.ts owns the stable quick-start builder; the terminal guide in skills/githits-mcp/SKILL.md is its exact public copy.
• Use package.json for root version, identity, and shared package metadata.
• Use server.json for registry transports and the hosted MCP endpoint.
• Use scripts/generate-plugin-assets.ts for host rendering and validation.

Transport Contract

• Every plugin and extension package uses https://mcp.githits.com. Claude, Codex, Cursor, and VS Code/GitHub Copilot OpenPlugin share generated .mcp.json; Gemini uses gemini-extension.json with httpUrl; and Antigravity uses mcp_config.json with serverUrl.
• The hosted server lives in the separate remote-mcp repository and consumes released @githits/mcp for tool registration, descriptors, quick_start, and tool logic. Keep transport, request-scoped service composition, auth/session handling, deployment, and observability in remote-mcp; never reimplement package-owned MCP behavior there. Hosted descriptor changes take effect only after the package release is adopted and deployed by remote-mcp.
• Direct githits init configuration retains stdio except for Cursor, which is remote-only. Claude and Gemini CLI setup remove legacy plugin or extension state before installing the user-scoped stdio server.
• server.json advertises both remote and version-pinned npm stdio transports.

Do not change another host's transport without an explicit product decision.

Validation

Always run:

bun run plugins:generate
bun run plugins:check
bun test

Also run bun run build before signoff. Run the repository-required smoke suites when MCP, CLI, packaging, auth, or shared agent behavior changes. Run targeted bun run agent:e2e workloads when skills, instructions, descriptions, or agent-facing behavior change.

Guardrails

• Do not manually patch generated manifests to make a check pass.
• Do not add authored host-specific skill forks.
• Do not add Markdown plugin commands unless the command is an intentional, tested product surface.
• Stop if generated changes cannot be explained by canonical input changes.