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)
- 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.
- A shared spec depends on local paths or hidden startup fragments and fails on another host. Specs must be self-describing for portability.
- 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.
- 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:
- Author a spec
- Validate it (structural)
- Install it (into spec library)
- Instantiate it on a clean OpenRig environment
- 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.yamlformats; seeopenrig-architectskill) - Workflow specs (markdown/YAML files, daemon read-through cache via
workflow_specstable; seeworkflow-runtimeskill) - 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-architectskill — RigSpec / AgentSpec authoring disciplineworkflow-runtimeskill — workflow spec authoring + transactional-scribe contractrig-bundles-and-shareable-artifactsskill — bundle is the packaged form of specsextension-and-user-workspaceskill — extensions add runtime behavior; specs declare intentopenrig/docs/reference/rig-spec.md(product reference doc) — RigSpec format specificationopenrig/docs/reference/agent-spec.md(product reference doc) — AgentSpec format specification
04 同仓库更多 Skills
notes
Use when taking notes.
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.
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).
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.
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).
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.