# Specification System

Use when authoring rig specs, agent specs, workflow specs, startup/context fragments...

- Repository: https://github.com/mvschwarz/openrig (8541 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mvschwarz/openrig --skill specification-system -g -a claude-code -y`
Codex: `npx skills add mvschwarz/openrig --skill specification-system -g -a codex -y`
Cursor: `npx skills add mvschwarz/openrig --skill specification-system -g -a cursor -y`
Gemini CLI: `npx skills add mvschwarz/openrig --skill specification-system -g -a gemini-cli -y`

## Description

Use when authoring rig specs, agent specs, workflow specs, startup/context fragments, operating-mode declarations, or designing the user spec library. Covers the 4 failure modes (spec instantiates topology but not workflow/mode; spec depends on local paths and fails on another host; agents modify specs as one-off files instead of preserving reusable intent; validation proves YAML shape but not whether topology can run) and the validation-vs-runtime-realization distinction.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Specification System

The declarative primitive family for OpenRig intent: **rig specs, agent
specs, workflow specs, startup/context fragments, operating-mode
declarations, and the user spec library that stores and reuses them.**

Specs are how humans and agents describe **repeatable topology and
behavior** without re-explaining it in chat. They are also shareable
artifacts: a user should be able to publish a spec or spec family so
another user can instantiate the same rig shape, role structure, or
workflow pattern.

**Without a dependable spec primitive, OpenRig depends on manual
startup prompts and tribal memory.** That blocks repeatability, product
demos, rig bundles, and autonomous rig construction.

## Use this when

- Authoring a RigSpec / AgentSpec / workflow spec
- Designing a startup/context fragment
- Reasoning about spec-library lifecycle (validation, sharing, upgrade semantics)
- Auditing a spec for portability (does it run on another host?)
- Distinguishing spec vs bundle vs extension cleanly

## Don't use this when

- The work is one-off and won't be reused. Manual rig assembly is fine for one-shot work.
- The intent is to package a topology + workflow as a shareable artifact. That's `rig-bundles-and-shareable-artifacts`.
- The intent is to add runtime behavior. That's `extension-and-user-workspace`.

## Failure modes (4)

The rest: https://github.com/mvschwarz/openrig/blob/HEAD/packages/daemon/specs/agents/shared/skills/core/specification-system/SKILL.md