XOps — Agentic Operations Harness
XOps is an open-source, agent-agnostic Agentic Operations Harness for DevOps, Platform Engineering, and SRE teams. It transforms operational knowledge (runbooks, playbooks, SOPs, troubleshooting guides, tribal knowledge) into portable, executable, testable, governed, and continuously improving skills. It does not replace AI coding agents (Claude Code, Codex, Cursor, OpenCode, Gemini CLI) — it amplifies them by providing the missing operational execution layer beneath every agent.
Positioning: "Terraform for Operational Intelligence" — as Terraform standardized Infrastructure as Code and Kubernetes standardized container orchestration, XOps aims to standardize Operational Intelligence.
- Repository: github.com/agenticdevops/xops
- Website: https://xops.bot
Core Value: An SRE team can convert an existing runbook into an executable XOps Skill and run it from any supported AI agent with consistent, governed behavior — reasoning stays with the agent, execution stays deterministic.
- Tech stack: TypeScript/Node — fastest iteration, matches MCP SDK + agent ecosystem (user decision, overriding PRD's Rust lean)
- Distribution: npm + npx (
npm install -g xops/npx xops) — Node presence is a safe assumption for AI-agent users - License: Apache 2.0 — patent grant, enterprise-friendly, standard for infra tooling
- Compatibility: Must reuse SKILL.md and MCP standards; agent-agnostic architecture even though MVP targets Claude Code + Codex
- Execution: Local only for MVP — no cloud service
- Sequencing: Design package (ADRs, specs) is produced and reviewed BEFORE implementation begins — reduces later architectural refactoring. Implementation then proceeds as vertical capability slices, not horizontal layers
- Executable Architecture Rule: Every implementation phase must end with a working
xopscommand demonstrating the newly introduced capability, validated by an end-to-end demo. Architecture is validated by real workflows, not internal APIs or docs - Milestone questions: Each slice answers one question — Can I write a skill? Can Claude execute it? Can Codex execute the same one? Can policy stop dangerous actions? Can we test it? Can we learn from it?
| Technology | Version | Purpose | Why Recommended |
|---|---|---|---|
| commander | ^14.0.0 |
CLI framework — subcommand dispatch, flags, help text | 220 kB install vs oclif's 12 MB+. 35M weekly downloads. Stable API since v8. XOps has 8-10 subcommands — exactly commander's sweet spot. oclif's plugin architecture isn't needed; citty (v0.2.x) is too new and opinionated for a public-facing DevOps tool |
| @modelcontextprotocol/sdk | ^1.x (stable) |
MCP server — expose skills as MCP tools via stdio transport | v1.x is the current production-stable release. v2 split packages (@modelcontextprotocol/server, @modelcontextprotocol/client) are in beta (2.0.0-beta.2 as of 2026-07-02) with stable release targeting 2026-07-28. Pin to v1 until v2 ships stable; v1 receives bug/security fixes for 6 months post-v2. Migration is codemod-assisted |
| zod | ^4.0.0 |
Schema validation — SKILL.md frontmatter, policy.yaml, CLI inputs, MCP tool inputSchema | Zod v4 is the current stable release (latest 4.4.3 as of 2026-07). 6.5x faster than v3 on safeParse, dramatically reduced TypeScript instantiations (25K→175 per compile). Import via "zod/v4/core" permalink for library-safe usage |
| TypeScript | ^5.5.0 |
Language | Node 20+ required; TS 5.x unlocks satisfies, improved inference, --verbatimModuleSyntax. Use "moduleResolution": "bundler" with tsup |
| Node.js | >=20.0.0 |
Runtime | LTS floor. MCP SDK v2 requires Node 20+. util.parseArgs (used by citty, useful reference), native fetch, native ESM. Also minimum for Claude Code / Codex users |
| Library | Version | Purpose | When to Use |
|---|---|---|---|
| gray-matter | ^4.0.3 |
SKILL.md frontmatter parsing (YAML front matter → JS object + body) | Every time a SKILL.md is parsed. Battle-tested by Gatsby, Astro, Next.js, Vitepress. Returns { data, content } cleanly. Lighter than pulling in all of remark |
yaml (eemeli/yaml) |
^2.8.0 |
YAML parsing/serialization for metadata.yaml, policy.yaml, fixtures/*.yaml |
For all YAML files that are NOT markdown frontmatter. Supports YAML 1.2, has excellent TypeScript types, min TS version 5.9. Do NOT use js-yaml for new code — eemeli/yaml is strictly better-typed |
| @clack/prompts | ^0.10.0 |
Interactive CLI prompts (xops init, xops skill new scaffolding) |
Wizard-style interactions only. TypeScript-native, ESM, ships beautiful styling by default. Handles cancellation via typed symbol (safer than undefined). Replaces inquirer for all new work |
| picocolors | ^1.1.0 |
Terminal color output for non-interactive CLI feedback | Status messages, lint output, eval results. 7 kB, CJS+ESM, actively maintained as of 2025. Use instead of chalk (ESM-only) or kleur (unmaintained since 2023) |
| pino | ^9.0.0 |
Structured telemetry logging to local file | Local execution logs: skill runs, durations, success/fail, approvals, overrides. Fastest Node logger (2-3x Winston), worker-thread transports, OpenTelemetry bridge ready. Use pino-pretty transport for human-readable dev output |
| execa | ^9.0.0 |
Child process execution for skill scripts | Runs the shell scripts within skills. Handles streams, exit codes, timeouts cleanly. ESM-only. DO NOT use Node's built-in child_process.exec — execa is the standard for this class of tool |
| @sindresorhus/is | ^6.0.0 |
Type guards for runtime input validation | Optional — use when zod is overkill for internal runtime checks |
| Tool | Purpose | Notes |
|---|---|---|
pnpm ^9.x |
Package manager + workspace protocol | Strict isolation, 40% less disk than npm, workspace:* protocol for cross-package refs. Single-package MVP is fine with npm, but use pnpm from day one if monorepo is planned |
Turborepo ^2.5.x |
Monorepo task orchestration and caching | Add when splitting into packages (e.g., @xops/cli, @xops/runtime, @xops/sdk). Not needed for MVP if staying single-package. pnpm workspaces + turborepo tasks reduce CI build times by ~42% via remote caching |
tsup ^8.x |
TypeScript bundler for npm/npx distribution | Wraps esbuild. Zero-config dual ESM+CJS output, .d.ts generation, shebang injection. Standard for TypeScript CLI + library authors in 2026. Use tsup src/index.ts --format esm,cjs --dts --clean |
vitest ^4.1.0 |
Unit + integration testing | Current stable: 4.1.10 (2026-07-06). 28x faster than Jest on warm runs. First-class ESM, TypeScript without transform config, native projects config for monorepo (replaces deprecated workspace config in 3.2+). Choose this over Jest for all new TypeScript projects in 2026 |
changesets ^2.27.0 |
Changelog management + versioning | Manages CHANGELOG.md entries and bumps package versions. Required for semantic versioning discipline. Integrates with pnpm workspaces for monorepo releases |
- OPA requires either a sidecar process (Go binary), REST API overhead, or WebAssembly compilation. For a local-first CLI tool with two policy modes, this is massive overkill
- A typed TypeScript
PolicyEvaluatorwith apolicy.yamlschema validated by Zod covers the MVP completely - OPA is the right choice post-MVP if skills need fine-grained Rego policies or enterprise RBAC. The architecture should allow plugging it in later
- XOps evals are fixture-driven (input → expected output → score), not LLM-as-judge
- External eval frameworks are Python-first; adding a Python dependency for a TypeScript CLI violates distribution simplicity
- Custom vitest-based eval harness: load fixture YAML → invoke skill runner → assert on exit code, stdout patterns, created resources. vitest's
describe/it/expectcovers this completely - Post-MVP: adopt
langchain-ai/agentevals(TypeScript + MIT) for trajectory-based evaluation when LLM-as-judge scoring is needed
| Recommended | Alternative | When to Use Alternative |
|---|---|---|
| commander | oclif | If XOps grows to 20+ commands maintained by multiple teams and plugin extensibility is a first-class requirement. oclif's 12 MB footprint and scaffolding overhead aren't worth it at 8-10 commands |
| commander | citty (unjs) | citty is elegant and zero-dep but at v0.2.x — too young for a DevOps tool users will depend on. Revisit at v1.0 |
| gray-matter | remark-frontmatter | Only if XOps builds a full Markdown AST pipeline (e.g., transforming SKILL.md into rendered docs). For pure data extraction, gray-matter is simpler |
yaml (eemeli) |
js-yaml | js-yaml is fine, but eemeli/yaml has better TypeScript types, YAML 1.2 compliance, and active development. The API is nearly identical — no reason to choose js-yaml for greenfield |
| @clack/prompts | inquirer | inquirer has 5M weekly downloads vs clack's 500K, so it has a larger community. Choose inquirer if you need highly custom prompt types not supported by clack |
| pino | winston | winston's 80+ transport ecosystem is valuable if you need multiple log destinations out of the box. For local-only telemetry files, pino's performance advantage wins |
| tsup | rollup | rollup has better tree-shaking for libraries consumed by browsers. For a Node CLI + MCP server, tsup's defaults are correct and simpler |
| Custom policy | OPA | Use OPA when policy complexity requires Rego DSL, multiple policy sources, or enterprise audit trails. Wire the interface now; swap implementation post-MVP |
| Custom eval engine | langchain agentevals | When LLM-as-judge scoring, trajectory evaluation, or multi-step agent assessment is needed. Post-MVP upgrade path |
| Avoid | Why | Use Instead |
|---|---|---|
@modelcontextprotocol/server (v2 beta) |
Beta as of 2026-07-08; API can change before 2026-07-28 stable release. Breaking your distribution on beta is a bad look for a DevOps tool | @modelcontextprotocol/sdk v1.x until v2 ships stable |
kleur |
Unmaintained since 2023, no 2025 releases | picocolors (7 kB, CJS+ESM, maintained) |
chalk for CJS projects |
ESM-only since chalk v5. CLI tools often need CJS compat for older runtimes | picocolors or ansis (ESM+CJS) |
js-yaml for new code |
Superseded by yaml (eemeli) — better types, YAML 1.2 |
yaml package |
jest |
5-28x slower than vitest; no first-class ESM; requires babel transform for TS | vitest v4.x |
ts-node |
Slow startup, legacy. MCP SDK v2 is ESM-only which ts-node handles poorly | tsx or tsup for builds; vitest handles TS in tests |
yargs |
Heavier than commander, bulkier API surface, less ergonomic for subcommand CLIs | commander |
| OPA for MVP | Process overhead, external binary dependency, Rego learning curve — all unjustified for two policy modes | Custom TypeScript PolicyEvaluator with Zod-validated schema |
Raw child_process.exec |
Callback-based, no stream control, error handling is manual | execa v9+ (async/await, typed, stream support) |
- Single
package.json,src/containscli/,runtime/,mcp/,sdk/,eval/ - tsup builds all entrypoints from one config
- No Turborepo needed; pnpm or npm both work
packages/cli— commander binary,@xops/clipackages/runtime— skill executor, context loader, policy enginepackages/sdk— SKILL.md parser, scaffolding, typespackages/mcp— MCP server wrapping runtimepackages/eval— fixture loader, scorer, reporter- pnpm workspaces + Turborepo
taskspipeline - MVP: stdio transport (agents connect directly via
xops mcp) - Post-MVP: streamable HTTP transport via
@modelcontextprotocol/honoadapter once v2 is stable - Use
McpServer.registerTool()with Zod inputSchema (MCP SDK v1 supports Zod natively) - gray-matter extracts frontmatter → validate with Zod schema → strong-typed
SkillManifestinterface - Body (markdown) preserved separately for human display
- Never mutate the source file; work from parsed in-memory representation
| Package A | Compatible With | Notes |
|---|---|---|
zod@^4.0.0 |
@modelcontextprotocol/sdk@^1.x |
MCP SDK v1 uses Zod for tool schemas. v2 uses "Standard Schema" protocol (Zod v4, Valibot, ArkType all work) |
zod@^4.0.0 |
vitest@^4.1.0 |
No conflicts. Zod v4 ships its own types |
typescript@^5.5.0 |
tsup@^8.x |
tsup uses esbuild internally; TS version only affects tsc for type-checking pass |
@modelcontextprotocol/sdk@^1.x |
Node.js >=18 |
v1 requires Node 18+; target Node 20+ for v2 readiness |
execa@^9.0.0 |
"type": "module" in package.json |
execa v9 is ESM-only; requires ESM package or dynamic import |
vitest@^4.1.0 |
vite@^6.x |
vitest 4 pairs with vite 6; no explicit vite dependency needed for Node-only CLI testing |
/modelcontextprotocol/typescript-sdk(Context7) — server setup, tool registration, stdio transport patterns; confirmed v1.x stable / v2 beta split- MCP SDK Beta Announcement — confirmed v2 package names, stable date, Node 20 requirement
- Building a production TypeScript CLI in 2026 — commander vs oclif quantitative comparison (220 kB vs 12 MB), command-count heuristic — MEDIUM confidence (single article, but numbers match other sources)
/colinhacks/zod(Context7) — v4/v4/core permalink import pattern, v3/v4 coexistence- Zod npm — confirmed v4.4.3 as latest stable (July 2026)
- Vitest 4.0 release — confirmed vitest 4.1.10 current stable, projects config replacing workspace
- Turborepo + pnpm 2026 guide — Turborepo 2.5.x, pnpm catalogs, changesets pattern — MEDIUM confidence
- WebSearch: picocolors maintenance status, execa ESM-only, clack/prompts vs inquirer — HIGH confidence (multiple sources agree)
- WebSearch: OPA Node.js integration — confirmed viable post-MVP but overkill for two-mode policy — HIGH confidence
Conventions not yet established. Will populate as patterns emerge during development.
Architecture not yet mapped. Follow existing patterns found in the codebase.
No project skills found. Add skills to any of: .claude/skills/, .agents/skills/, .cursor/skills/, .github/skills/, or .codex/skills/ with a SKILL.md index file.
Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
Use these entry points:
/gsd:quickfor small fixes, doc updates, and ad-hoc tasks/gsd:debugfor investigation and bug fixing/gsd:execute-phasefor planned phase work
Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
Profile not yet configured. Run
/gsd:profile-userto generate your developer profile. This section is managed bygenerate-claude-profile-- do not edit manually.