AGENT-SPEC.md currently combines several different concerns in one pinned runtime manual: the purpose of Agent Spec, durable requirements, concrete KDL syntax, current st2 behavior, authoring guidance, and commit-specific conformance details.
That makes implementation snapshots easy to document, but makes the durable Agent Spec contract difficult to review or evolve independently from st2. The eval corpus already treats executable evidence as authoritative, so Agent Spec should use the same evidence-derived VRS discipline.
Proposed direction
Refactor Agent Spec into a proper VRS with a clear separation:
Agent Spec vision
-> testable requirements
-> concrete specification
-> pinned st2 conformance profile and executable eval evidence
The durable VRS should describe Agent Spec rather than st2 as a product. In particular:
- vision explains why a portable, inspectable, self-contained agent declaration exists;
- requirements state testable runtime-independent constraints;
- spec defines the concrete declaration model and lifecycle semantics;
- ontology defines terms such as Agent, Resource binding, task, declaration revision, launch generation, publisher, and runtime observation;
- pinned st2 commits, executable hashes, command help, and implementation-specific caveats live in a conformance profile rather than the timeless contract; and
- every normative claim retains a link to maintained executable evidence.
AGENT-SPEC.md can remain the canonical entry point, but should become a concise projection/index rather than a second overlapping specification.
Acceptance questions
- What is stable Agent Spec intent versus current st2 realization?
- Which requirements are already proven by maintained cells, and which are only implementation observations?
- How does a capability graduate from experiment to requirement/specification?
- How are alternative or successor runtimes evaluated against the same contract?
- How do we avoid duplicating normative text between the VRS,
AGENT-SPEC.md, runtime docs, and cell READMEs?
- Which VRS artifacts are protected, and what evidence is required to change them?
The redesign should preserve the repository's evidence-before-prose rule and should not introduce a second declaration model or speculative runtime features.
Related: #37, #40, #41, #44, compoundingtech/st2#77, and compoundingtech/st2#86.
AGENT-SPEC.mdcurrently combines several different concerns in one pinned runtime manual: the purpose of Agent Spec, durable requirements, concrete KDL syntax, current st2 behavior, authoring guidance, and commit-specific conformance details.That makes implementation snapshots easy to document, but makes the durable Agent Spec contract difficult to review or evolve independently from st2. The eval corpus already treats executable evidence as authoritative, so Agent Spec should use the same evidence-derived VRS discipline.
Proposed direction
Refactor Agent Spec into a proper VRS with a clear separation:
The durable VRS should describe Agent Spec rather than st2 as a product. In particular:
AGENT-SPEC.mdcan remain the canonical entry point, but should become a concise projection/index rather than a second overlapping specification.Acceptance questions
AGENT-SPEC.md, runtime docs, and cell READMEs?The redesign should preserve the repository's evidence-before-prose rule and should not introduce a second declaration model or speculative runtime features.
Related: #37, #40, #41, #44, compoundingtech/st2#77, and compoundingtech/st2#86.