AGENT SKILL

specification-system

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.

License 许可
Apache-2.0
最近更新
2026-11-12
Stars
★ 16
Forks
4

01 前言 Front Matter

name
specification-system
metadata
{ "openrig": { "stage": "factory-approved", "sibling_skills": [ "rig-lifecycle", "topology-mutation-and-seat-management", "seat-scaling-and-specialization", "cross-host-rig-commands", "sidecar-operator", "rig-bundles-and-shareable-artifacts", "extension-and-user-workspace" ] }, "cli_surfaces_referenced": [ "agent", "bundle", "spec", "specs" ] }
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.

03 SKILL.md 正文

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)

  1. A spec can instantiate a topology but not the workflow or operating mode needed to use it. Topology is necessary but not sufficient — workflow and operating mode must be declared too.
  2. A shared spec depends on local paths or hidden startup fragments and fails on another host. Specs must be self-describing for portability.
  3. Agents modify specs as one-off files instead of preserving reusable user/library intent. Specs are reusable; treating each instance as one-off destroys the primitive's value.
  4. Validation proves YAML shape but not whether the declared topology can actually run. Structural validation is not enough; runtime realization is the real proof.

Proof standard

Proof should:

  1. Author a spec
  2. Validate it (structural)
  3. Install it (into spec library)
  4. Instantiate it on a clean OpenRig environment
  5. Show both structural validation AND runtime realization

Validation alone is insufficient.

Spec / bundle / extension boundary

Concept Declares Example
Spec Topology / role / workflow shape (declarative intent) rig.yaml, agent.yaml, workflow.yaml
Bundle Spec(s) + supporting fragments packaged for shareable instantiation A Velocity Team bundle
Extension Runtime behavior added to user workspace RigX command, custom view

Don't conflate them. The contract should distinguish spec, bundle, and extension cleanly.

Currently shipped surfaces

OpenRig already has:

  • RigSpec / AgentSpec authoring (agent.yaml, rig.yaml formats; see openrig-architect skill)
  • Workflow specs (markdown/YAML files, daemon read-through cache via workflow_specs table; see workflow-runtime skill)
  • Bundle/spec command surface (rig bundle / spec / agent / specs ls/show/preview/add/sync/remove/rename)
  • Spec library (filesystem-backed at packages/daemon/specs/ + ~/.openrig/specs/ per cli-reference.md)

Not yet shipped:

  • Spec library lifecycle (validation, sharing, upgrade) treated as a first-class primitive
  • Cross-host spec sharing
  • Marketplace / public registry

See also

  • openrig-architect skill — RigSpec / AgentSpec authoring discipline
  • workflow-runtime skill — workflow spec authoring + transactional-scribe contract
  • rig-bundles-and-shareable-artifacts skill — bundle is the packaged form of specs
  • extension-and-user-workspace skill — extensions add runtime behavior; specs declare intent
  • openrig/docs/reference/rig-spec.md (product reference doc) — RigSpec format specification
  • openrig/docs/reference/agent-spec.md (product reference doc) — AgentSpec format specification

04 同仓库更多 Skills

mvschwarz
mvschwarz/openrig-world

notes

Use when taking notes.

★ 16
mvschwarz
mvschwarz/openrig-world

software-for-agents

Use when older OpenRig instructions name software-for-agents or describe agent-in-the-middle or studio software under the former skill name.

★ 16
mvschwarz
mvschwarz/openrig-world

session-compaction-and-restore

Use when reasoning about what survives compaction/context-loss/restart/seat-refresh, designing a high-fidelity restore packet, or distinguishing native runtime resume vs fork vs artifact-backed mental-model rebuild. Covers the 4 failure modes that prevent honest restore (compacted seat drops hot potato; restore packet preserves details but loses product intent; runtime resume mistaken for handover or fork; rebuilt seat starts with stale instructions).

★ 16
mvschwarz
mvschwarz/openrig-world

seat-continuity-and-handover

Use when replacing a seat's occupant (rebuild/handover/swap), reasoning about stable-seat-identity vs fluid-occupant-identity, choosing an old-occupant disposition (retire/advise/shadow), or recording provenance for an occupant change. Two independent outcomes (continuityOutcome + seatBindingOutcome) and the 5 failure modes that prevent silent dishonesty.

★ 16
mvschwarz
mvschwarz/openrig-world

retiring-and-inheriting-a-seat

Use when you are a sitting agent near your context threshold (~85%) and a PLANNED seat transition is due — retire deliberately and hand your seat to a fresh successor primed from a packet, rather than let compaction degrade you. Covers the handover packet, the append-only lineage ledger (one row per tenure), physical-seat continuity, the do-not-over-inherit framing, the optional warm-handoff window, and wake-v0 (consulting a retired predecessor). NOT for unplanned compaction/crash recovery (session-compaction-and-restore / claude-compaction-restore) and NOT the seat-binding primitive mechanics (seat-continuity-and-handover).

★ 16
mvschwarz
mvschwarz/openrig-world

refocusing

Use when a long-running agent may have lost the product outcome, when context was compacted, when work has crossed a major boundary, or when a fresh path-based trace is needed before the next consequential action. Not for fresh-session orientation, waking an idle seat, or checkpoints.

★ 16