specification-system

1# Specification System
2 
3The declarative primitive family for OpenRig intent: **rig specs, agent
4specs, workflow specs, startup/context fragments, operating-mode
5declarations, and the user spec library that stores and reuses them.**
6 
7Specs are how humans and agents describe **repeatable topology and
8behavior** without re-explaining it in chat. They are also shareable
9artifacts: a user should be able to publish a spec or spec family so
10another user can instantiate the same rig shape, role structure, or
11workflow pattern.
12 
13**Without a dependable spec primitive, OpenRig depends on manual
14startup prompts and tribal memory.** That blocks repeatability, product
15demos, rig bundles, and autonomous rig construction.
16 
17## Use this when
18 
19- Authoring a RigSpec / AgentSpec / workflow spec
20- Designing a startup/context fragment
21- Reasoning about spec-library lifecycle (validation, sharing, upgrade semantics)
22- Auditing a spec for portability (does it run on another host?)
23- Distinguishing spec vs bundle vs extension cleanly
24 
25## Don't use this when
26 
27- The work is one-off and won't be reused. Manual rig assembly is fine for one-shot work.
28- The intent is to package a topology + workflow as a shareable artifact. That's `rig-bundles-and-shareable-artifacts`.
29- The intent is to add runtime behavior. That's `extension-and-user-workspace`.
30 
31## Failure modes (4)
32…