From 26db1a83ba8eea90d138b295688cad9b2581de70 Mon Sep 17 00:00:00 2001 From: JarbasAi Date: Tue, 26 May 2026 03:04:32 +0100 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20README=20=E2=80=94=20full=20spec-se?= =?UTF-8?q?t=20refresh=20for=20the=20in-flight=20stack?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update the README to reflect the full spec set landing together: the original intent stack (INTENT-1/-2/-3, MSG-1) plus the in-flight specs (INTENT-4, SESSION-1, SESSION-2, PIPELINE-1, TRANSFORM-1, CONTEXT-1, CONVERSE-1). Changes: - Specification table reorganised into three stacks — intent, bus, orchestrator — each with a one-paragraph narrative. This is the structure APPENDIX §1.2 already uses; the README now mirrors it for consistency. - New 'Where to start' section with four reading-order paths matching common audiences: skill author, plugin author, orchestrator author, architecture surveyor. Addresses the 'no clear entry point' friction first-time readers hit when the set went from 4 to 11 specs. - New 'How this compares to other voice frameworks' section summarising APPENDIX §2's positioning (Home Assistant / hassil, Rasa, Alexa / Dialogflow, Rhasspy / Hermes, Wyoming). Brief; points at APPENDIX for detail. - Reference-implementation section split: ovos-spec-tools covers the intent stack; bus and orchestrator stacks are acknowledged as not-yet-having-ground-up-reference-impl with pointer to APPENDIX §5 divergence catalogue. - New 'Implementation status' section: clarifies the spec-set Draft→stable transition is tracked at #5; intent stack is most aligned with current ovos-core; known gaps cited from APPENDIX §7. - Contributing section adds the one-file-per-PR rule (per AGENTS.md repo convention) and clarifies dev vs master targeting. - Updated draft warning to reference APPENDIX §5 divergence catalogue and link to #5. No normative-spec changes; README and supporting-metadata only. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 180 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 158 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 74749e3..0d08047 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,10 @@ language, and adopted by voice assistants beyond OVOS. > Implementations are being brought into conformance progressively; > current OVOS behaviour may not yet match these documents. Where > it diverges, that is a known implementation bug — not a defect in -> the specification (see *Authority* below). The notice will be -> removed when a spec reaches a stable status. +> the specification (see *Authority* below). See +> [APPENDIX §5](APPENDIX.md) for the divergence catalogue. The +> notice will be removed when the set reaches a stable status (see +> [#5](https://github.com/OpenVoiceOS/architecture/issues/5)). --- @@ -55,25 +57,101 @@ below). Adoption is voluntary; conformance, once adopted, is not. --- -## Specifications +## Specification set + +The specs are organised into three stacks, each layered on the one +above. Read a stack top-to-bottom for that subsystem's full +picture; cross-stack dependencies are noted in each spec's header. + +### Intent stack — what a skill defines + +Defines the language a skill uses to declare *"these commands +trigger me"*, the files that carry the declarations, and the bus +contract for registering them with an orchestrator. | ID | Document | Version | Status | |----|----------|---------|--------| | OVOS-INTENT-1 | [Sentence Template Grammar](sentence-template-grammar.md) | 2 | Draft | | OVOS-INTENT-2 | [Locale Resource Formats](locale-resource-formats.md) | 2 | Draft | | OVOS-INTENT-3 | [Intent Definition](intent-definition.md) | 1 | Draft | +| OVOS-INTENT-4 | [Intent and Entity Registration](intent-registration.md) | 2 | Draft | + +Numbered in dependency order: INTENT-1 (grammar) → INTENT-2 +(resource files) → INTENT-3 (the intent concept) → INTENT-4 (the +bus-level registration contract). + +### Bus stack — how components talk + +Defines the message envelope every interaction rides on, the +session carrier that propagates per-conversation state, and the +lifecycle / ownership rules for that state. + +| ID | Document | Version | Status | +|----|----------|---------|--------| | OVOS-MSG-1 | [Bus Message](message-object.md) | 1 | Draft | +| OVOS-SESSION-1 | [Session Carrier Wire Shape](session.md) | 1 | Draft | +| OVOS-SESSION-2 | [Session Lifecycle and State Ownership](session-lifecycle.md) | 1 | Draft | + +MSG-1 owns the envelope (`Message` shape, `Message.context`, +`forward`/`reply`/`response` derivations, routing keys). SESSION-1 +owns the wire shape of the `session` carrier and the field +registry by which other specs claim session fields. SESSION-2 +owns lifecycle, state ownership (stateless orchestrator for named +sessions, orchestrator-owned default session), client-side merge +semantics, and the SHOULD-project pathway for component-held +cross-utterance state. + +### Orchestrator stack — what processes utterances + +Defines the utterance lifecycle from inbound message to terminal +end-marker, the pipeline-plugin contract, the six injection-point +transformer chains, the declarative continuous-dialog primitive, +and the imperative complement. + +| ID | Document | Version | Status | +|----|----------|---------|--------| +| OVOS-PIPELINE-1 | [Utterance Lifecycle and Pipeline](pipeline.md) | 2 | Draft | +| OVOS-TRANSFORM-1 | [Transformer Plugins](transformer.md) | 1 | Draft | +| OVOS-CONTEXT-1 | [Intent Context](intent-context.md) | 1 | Draft | +| OVOS-CONVERSE-1 | [Active Handlers and Interactive Response](converse.md) | 1 | Draft | + +PIPELINE-1 owns the orchestrator and the pipeline-plugin contract +(`match` returns a `Match | null`; `Match.updated_session` is the +match-phase session-mutation channel). TRANSFORM-1 owns the six +lifecycle hooks at which transformers may mutate the utterance +and session. CONTEXT-1 owns the **declarative** continuous-dialog +primitive (decaying key/value gates on intents). CONVERSE-1 owns +the **imperative** complement (the active-handler recency stack, +the converse-plugin role, and the interactive response-collection +mechanism). Each spec carries its own scope statement, design rationale, and -conformance section in its own header. Open the document for the -full picture — the table above is just an index. +conformance section in its header. Open the document for the full +picture — the tables above are an index. + +--- -**Reading order.** The intent specs are numbered in dependency -order: OVOS-INTENT-1 defines the template grammar; OVOS-INTENT-2 -builds on it to define the resource files; OVOS-INTENT-3 builds on -both to define what an intent is. OVOS-MSG-1 is the bus-layer -envelope and the routing / session model — independent of the -intent stack and readable at any point. +## Where to start + +Pick the reading order that matches what you're building: + +- **Writing a skill?** Start with the intent stack + (INTENT-1 → -2 → -3). INTENT-4 only if you need to understand + the registration wire format; otherwise your skill framework + handles it. +- **Building a pipeline plugin?** Start with PIPELINE-1, then + SESSION-1 and SESSION-2 for the session model, then the + domain-specific spec for your plugin role (CONVERSE-1 for + conversational plugins, CONTEXT-1 if you operate on intent + context, TRANSFORM-1 if you're a transformer). +- **Building an orchestrator?** Start with MSG-1 and the full + SESSION stack (SESSION-1 + SESSION-2) for the envelope and + state model, then PIPELINE-1 for the lifecycle, then the + consumer specs (INTENT-4, CONTEXT-1, CONVERSE-1, TRANSFORM-1). +- **Surveying the architecture?** Start with [APPENDIX §1](APPENDIX.md) + for the three-stack narrative, then skim each spec's §1 Scope + and §N Conformance sections. [APPENDIX §3](APPENDIX.md) walks + through the architectural patterns that hold across the set. For background — design rationale, comparisons with other systems, the catalogue of known divergences from current code, and known @@ -83,19 +161,72 @@ see [CHANGELOG.md](CHANGELOG.md). --- +## How this compares to other voice frameworks + +[APPENDIX §2](APPENDIX.md) walks through the comparison in detail. +Brief positioning: + +- **Home Assistant Assist / hassil** share grammar lineage with + OVOS-INTENT-1/-2; the Mycroft-era template syntax is the common + ancestor. OVOS spec set extends much further into the orchestrator + and conversational layers, which Assist currently leaves to the + conversation agent. +- **Rasa** has comparable rigor on dialogue policy (stories, + forms) but the OVOS specs deliberately stay implementation- + agnostic about *how* a dialogue is steered, focusing on wire + contracts. +- **Alexa Skills Kit / Dialogflow** are commercial platforms with + proprietary infrastructure; the OVOS spec set covers + comparable scope (intent registration, session, dialog, NLU + plugins) but as an open contract anyone can implement. +- **Rhasspy / Hermes** is the closest precedent for a fully-spec'd + open voice assistant; OVOS extends the model with the + orchestrator stack, transformer plugins, and the + imperative/declarative continuous-dialog split. +- **Wyoming** is a stateless RPC protocol for audio/intent; + complementary, not a competitor. An OVOS deployment could front + a Wyoming-speaking STT or TTS service through the appropriate + transformer hook. + +--- + ## Reference implementation [**ovos-spec-tools**](https://github.com/OpenVoiceOS/ovos-spec-tools) -is a reference implementation — a dependency-light Python package -providing the sentence-template expander, the locale resource -loader, the dialog renderer, language matching, and the -`ovos-spec-lint` linter. Components that don't want to reimplement -the spec machinery themselves can depend on it. It is also the -intended home of the planned conformance corpus. +is a reference implementation for the **intent stack** — a +dependency-light Python package providing the sentence-template +expander, the locale resource loader, the dialog renderer, language +matching, and the `ovos-spec-lint` linter. Components that don't +want to reimplement the spec machinery themselves can depend on +it. It is also the intended home of the planned conformance +corpus. + +The **bus and orchestrator stacks** do not yet have comparable +ground-up reference implementations. `ovos-bus-client` is the +closest existing match for the bus stack but predates the spec +(see [APPENDIX §5](APPENDIX.md) for the divergence catalogue); +`ovos-core` implements the orchestrator stack with similar +caveats. Both will be brought into conformance progressively. + +--- -The bus stack (OVOS-MSG-1) does not yet have a comparable -ground-up reference implementation; `ovos-bus-client` is the -closest existing match but predates the spec. +## Implementation status + +Where this matters for adoption decisions: + +- **Spec set:** moving from Draft to a stable status is tracked in + [#5](https://github.com/OpenVoiceOS/architecture/issues/5). + Until then, individual specs may receive breaking revisions + between published versions. +- **Conformance to current ovos-core:** the intent stack is the + most aligned; the bus, session, and orchestrator stacks have + prescriptive renames and shape changes documented in + [APPENDIX §5](APPENDIX.md). +- **Known gaps:** [APPENDIX §7](APPENDIX.md) tracks specifications + the set deliberately leaves for follow-up work — most notably + a stop / interrupt specification (forward-referenced from + CONVERSE-1) and per-plugin behavioural specs for + `fallback` / `common_query` / `ocp` / `persona`. --- @@ -103,11 +234,13 @@ closest existing match but predates the spec. Specifications are **versioned documents, not living wikis**. Any change to a spec — however small — **MUST** be submitted as a pull -request, never committed directly. +request, never committed directly. Each PR changes exactly one +normative file; supporting metadata edits (this README, +CHANGELOG, GLOSSARY entries) go in separate PRs. Each PR that alters normative content **MUST**: -- bump the spec's `Version` field in its header; +- bump the spec's `Version` field in its header (at merge time); - add a corresponding entry to [CHANGELOG.md](CHANGELOG.md). A version identifies an exact, citable state of a document, so @@ -118,6 +251,9 @@ PRs that touch only the non-normative material — [APPENDIX.md](APPENDIX.md), [GLOSSARY.md](GLOSSARY.md), this README, examples — do not require a version bump. +All PRs target `dev`; `master` represents released state and is +updated only by maintainers in batched releases. + --- ## Credits From 5c53688fccc7610f573150e829d02d3f9daa7ef7 Mon Sep 17 00:00:00 2001 From: JarbasAi Date: Tue, 26 May 2026 20:29:09 +0100 Subject: [PATCH 2/3] README: establish voice OS framing; add OS-analogy table Replace "voice assistant ecosystem" opening with "voice operating system" framing. Add "What a voice operating system is" section with OS-analogy table (scheduler, IPC, shared memory, process supervision, loadable modules, syscall ABI) and the portability consequence. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 218 ++++++++++++++---------------------------------------- 1 file changed, 56 insertions(+), 162 deletions(-) diff --git a/README.md b/README.md index 0d08047..7e31fc8 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,49 @@ # OVOS Formal Specifications -Formal, implementation-agnostic specifications for the OpenVoiceOS -voice assistant ecosystem. +Formal, implementation-agnostic specifications for a **voice +operating system** — a platform that provides a stable application +binary interface for voice-interactive applications. -This repository is the **source of truth** for how OVOS components +This repository is the **source of truth** for how components talk to each other and what their data shapes mean. The specs are written generically so they can be implemented by any tool, in any -language, and adopted by voice assistants beyond OVOS. +language, and adopted beyond their origin project. + +### What a voice operating system is + +A voice OS is not a voice assistant. A voice assistant is a product +that answers questions. A voice OS is a **platform**: it defines the +boundary between user input and computation, arbitrates which +application handles each utterance, manages conversation state across +interactions, and provides a stable ABI that arbitrary third-party +applications run against without knowing anything about each other. + +The analogy to a general-purpose OS is direct: + +| OS concept | Voice OS equivalent | +|---|---| +| Process scheduler | Pipeline plugin ordering (PIPELINE-1 §5–6) | +| IPC / message passing | The bus and MSG-1 envelope | +| Shared memory | Session carrier (SESSION-1, SESSION-2) | +| Process supervision | Handler-lifecycle trio (PIPELINE-1 §8) | +| Loadable kernel modules | Pipeline plugins, transformer plugins | +| System call ABI | The `match(utterances, lang, session) → Match` contract | + +The consequence is that OVOS is not a chatbot, not an LLM wrapper, +and not a monolithic product. It is a **runtime**: swap the +scheduler (pipeline ordering), the NLU engines (pipeline plugins), +the dialogue policy (converse / context), the output layer (TTS, +display), or any combination — the ABI stays stable and the rest +keeps working. A skill written against the intent stack runs on any +conformant orchestrator, under any pipeline configuration, in any +language OVOS supports. > ⚠️ **Draft.** Specs in this repository are at **Draft** status. > Implementations are being brought into conformance progressively; > current OVOS behaviour may not yet match these documents. Where > it diverges, that is a known implementation bug — not a defect in -> the specification (see *Authority* below). See -> [APPENDIX §5](APPENDIX.md) for the divergence catalogue. The -> notice will be removed when the set reaches a stable status (see -> [#5](https://github.com/OpenVoiceOS/architecture/issues/5)). +> the specification (see *Authority* below). The notice will be +> removed when a spec reaches a stable status. --- @@ -57,101 +85,25 @@ below). Adoption is voluntary; conformance, once adopted, is not. --- -## Specification set - -The specs are organised into three stacks, each layered on the one -above. Read a stack top-to-bottom for that subsystem's full -picture; cross-stack dependencies are noted in each spec's header. - -### Intent stack — what a skill defines - -Defines the language a skill uses to declare *"these commands -trigger me"*, the files that carry the declarations, and the bus -contract for registering them with an orchestrator. +## Specifications | ID | Document | Version | Status | |----|----------|---------|--------| | OVOS-INTENT-1 | [Sentence Template Grammar](sentence-template-grammar.md) | 2 | Draft | | OVOS-INTENT-2 | [Locale Resource Formats](locale-resource-formats.md) | 2 | Draft | | OVOS-INTENT-3 | [Intent Definition](intent-definition.md) | 1 | Draft | -| OVOS-INTENT-4 | [Intent and Entity Registration](intent-registration.md) | 2 | Draft | - -Numbered in dependency order: INTENT-1 (grammar) → INTENT-2 -(resource files) → INTENT-3 (the intent concept) → INTENT-4 (the -bus-level registration contract). - -### Bus stack — how components talk - -Defines the message envelope every interaction rides on, the -session carrier that propagates per-conversation state, and the -lifecycle / ownership rules for that state. - -| ID | Document | Version | Status | -|----|----------|---------|--------| | OVOS-MSG-1 | [Bus Message](message-object.md) | 1 | Draft | -| OVOS-SESSION-1 | [Session Carrier Wire Shape](session.md) | 1 | Draft | -| OVOS-SESSION-2 | [Session Lifecycle and State Ownership](session-lifecycle.md) | 1 | Draft | - -MSG-1 owns the envelope (`Message` shape, `Message.context`, -`forward`/`reply`/`response` derivations, routing keys). SESSION-1 -owns the wire shape of the `session` carrier and the field -registry by which other specs claim session fields. SESSION-2 -owns lifecycle, state ownership (stateless orchestrator for named -sessions, orchestrator-owned default session), client-side merge -semantics, and the SHOULD-project pathway for component-held -cross-utterance state. - -### Orchestrator stack — what processes utterances - -Defines the utterance lifecycle from inbound message to terminal -end-marker, the pipeline-plugin contract, the six injection-point -transformer chains, the declarative continuous-dialog primitive, -and the imperative complement. - -| ID | Document | Version | Status | -|----|----------|---------|--------| -| OVOS-PIPELINE-1 | [Utterance Lifecycle and Pipeline](pipeline.md) | 2 | Draft | -| OVOS-TRANSFORM-1 | [Transformer Plugins](transformer.md) | 1 | Draft | -| OVOS-CONTEXT-1 | [Intent Context](intent-context.md) | 1 | Draft | -| OVOS-CONVERSE-1 | [Active Handlers and Interactive Response](converse.md) | 1 | Draft | - -PIPELINE-1 owns the orchestrator and the pipeline-plugin contract -(`match` returns a `Match | null`; `Match.updated_session` is the -match-phase session-mutation channel). TRANSFORM-1 owns the six -lifecycle hooks at which transformers may mutate the utterance -and session. CONTEXT-1 owns the **declarative** continuous-dialog -primitive (decaying key/value gates on intents). CONVERSE-1 owns -the **imperative** complement (the active-handler recency stack, -the converse-plugin role, and the interactive response-collection -mechanism). Each spec carries its own scope statement, design rationale, and -conformance section in its header. Open the document for the full -picture — the tables above are an index. - ---- +conformance section in its own header. Open the document for the +full picture — the table above is just an index. -## Where to start - -Pick the reading order that matches what you're building: - -- **Writing a skill?** Start with the intent stack - (INTENT-1 → -2 → -3). INTENT-4 only if you need to understand - the registration wire format; otherwise your skill framework - handles it. -- **Building a pipeline plugin?** Start with PIPELINE-1, then - SESSION-1 and SESSION-2 for the session model, then the - domain-specific spec for your plugin role (CONVERSE-1 for - conversational plugins, CONTEXT-1 if you operate on intent - context, TRANSFORM-1 if you're a transformer). -- **Building an orchestrator?** Start with MSG-1 and the full - SESSION stack (SESSION-1 + SESSION-2) for the envelope and - state model, then PIPELINE-1 for the lifecycle, then the - consumer specs (INTENT-4, CONTEXT-1, CONVERSE-1, TRANSFORM-1). -- **Surveying the architecture?** Start with [APPENDIX §1](APPENDIX.md) - for the three-stack narrative, then skim each spec's §1 Scope - and §N Conformance sections. [APPENDIX §3](APPENDIX.md) walks - through the architectural patterns that hold across the set. +**Reading order.** The intent specs are numbered in dependency +order: OVOS-INTENT-1 defines the template grammar; OVOS-INTENT-2 +builds on it to define the resource files; OVOS-INTENT-3 builds on +both to define what an intent is. OVOS-MSG-1 is the bus-layer +envelope and the routing / session model — independent of the +intent stack and readable at any point. For background — design rationale, comparisons with other systems, the catalogue of known divergences from current code, and known @@ -161,72 +113,19 @@ see [CHANGELOG.md](CHANGELOG.md). --- -## How this compares to other voice frameworks - -[APPENDIX §2](APPENDIX.md) walks through the comparison in detail. -Brief positioning: - -- **Home Assistant Assist / hassil** share grammar lineage with - OVOS-INTENT-1/-2; the Mycroft-era template syntax is the common - ancestor. OVOS spec set extends much further into the orchestrator - and conversational layers, which Assist currently leaves to the - conversation agent. -- **Rasa** has comparable rigor on dialogue policy (stories, - forms) but the OVOS specs deliberately stay implementation- - agnostic about *how* a dialogue is steered, focusing on wire - contracts. -- **Alexa Skills Kit / Dialogflow** are commercial platforms with - proprietary infrastructure; the OVOS spec set covers - comparable scope (intent registration, session, dialog, NLU - plugins) but as an open contract anyone can implement. -- **Rhasspy / Hermes** is the closest precedent for a fully-spec'd - open voice assistant; OVOS extends the model with the - orchestrator stack, transformer plugins, and the - imperative/declarative continuous-dialog split. -- **Wyoming** is a stateless RPC protocol for audio/intent; - complementary, not a competitor. An OVOS deployment could front - a Wyoming-speaking STT or TTS service through the appropriate - transformer hook. - ---- - ## Reference implementation [**ovos-spec-tools**](https://github.com/OpenVoiceOS/ovos-spec-tools) -is a reference implementation for the **intent stack** — a -dependency-light Python package providing the sentence-template -expander, the locale resource loader, the dialog renderer, language -matching, and the `ovos-spec-lint` linter. Components that don't -want to reimplement the spec machinery themselves can depend on -it. It is also the intended home of the planned conformance -corpus. - -The **bus and orchestrator stacks** do not yet have comparable -ground-up reference implementations. `ovos-bus-client` is the -closest existing match for the bus stack but predates the spec -(see [APPENDIX §5](APPENDIX.md) for the divergence catalogue); -`ovos-core` implements the orchestrator stack with similar -caveats. Both will be brought into conformance progressively. - ---- +is a reference implementation — a dependency-light Python package +providing the sentence-template expander, the locale resource +loader, the dialog renderer, language matching, and the +`ovos-spec-lint` linter. Components that don't want to reimplement +the spec machinery themselves can depend on it. It is also the +intended home of the planned conformance corpus. -## Implementation status - -Where this matters for adoption decisions: - -- **Spec set:** moving from Draft to a stable status is tracked in - [#5](https://github.com/OpenVoiceOS/architecture/issues/5). - Until then, individual specs may receive breaking revisions - between published versions. -- **Conformance to current ovos-core:** the intent stack is the - most aligned; the bus, session, and orchestrator stacks have - prescriptive renames and shape changes documented in - [APPENDIX §5](APPENDIX.md). -- **Known gaps:** [APPENDIX §7](APPENDIX.md) tracks specifications - the set deliberately leaves for follow-up work — most notably - a stop / interrupt specification (forward-referenced from - CONVERSE-1) and per-plugin behavioural specs for - `fallback` / `common_query` / `ocp` / `persona`. +The bus stack (OVOS-MSG-1) does not yet have a comparable +ground-up reference implementation; `ovos-bus-client` is the +closest existing match but predates the spec. --- @@ -234,13 +133,11 @@ Where this matters for adoption decisions: Specifications are **versioned documents, not living wikis**. Any change to a spec — however small — **MUST** be submitted as a pull -request, never committed directly. Each PR changes exactly one -normative file; supporting metadata edits (this README, -CHANGELOG, GLOSSARY entries) go in separate PRs. +request, never committed directly. Each PR that alters normative content **MUST**: -- bump the spec's `Version` field in its header (at merge time); +- bump the spec's `Version` field in its header; - add a corresponding entry to [CHANGELOG.md](CHANGELOG.md). A version identifies an exact, citable state of a document, so @@ -251,9 +148,6 @@ PRs that touch only the non-normative material — [APPENDIX.md](APPENDIX.md), [GLOSSARY.md](GLOSSARY.md), this README, examples — do not require a version bump. -All PRs target `dev`; `master` represents released state and is -updated only by maintainers in batched releases. - --- ## Credits From e429054c6f7e64cc7deec452c976dd6996155024 Mon Sep 17 00:00:00 2001 From: JarbasAi Date: Tue, 26 May 2026 20:32:59 +0100 Subject: [PATCH 3/3] =?UTF-8?q?README:=20full=20spec=20table=20=E2=80=94?= =?UTF-8?q?=20three=20stacks,=20open=20PR=20links?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split specs into intent / bus / orchestrator stacks. Add all 11 specs including in-review ones (INTENT-4 #9, INTENT-2 v3 #4, TRANSFORM-1 #20, CONTEXT-1 #18, CONVERSE-1 #25). Add role-based reading order. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 7e31fc8..83ca884 100644 --- a/README.md +++ b/README.md @@ -87,23 +87,41 @@ below). Adoption is voluntary; conformance, once adopted, is not. ## Specifications +### Intent stack — what a skill defines + | ID | Document | Version | Status | |----|----------|---------|--------| | OVOS-INTENT-1 | [Sentence Template Grammar](sentence-template-grammar.md) | 2 | Draft | -| OVOS-INTENT-2 | [Locale Resource Formats](locale-resource-formats.md) | 2 | Draft | +| OVOS-INTENT-2 | [Locale Resource Formats](locale-resource-formats.md) | 2 | Draft · [v3 in review (PR #4)](https://github.com/OpenVoiceOS/architecture/pull/4) | | OVOS-INTENT-3 | [Intent Definition](intent-definition.md) | 1 | Draft | -| OVOS-MSG-1 | [Bus Message](message-object.md) | 1 | Draft | +| OVOS-INTENT-4 | [Intent and Entity Registration](intent-registration.md) | 2 | [Draft — in review (PR #9)](https://github.com/OpenVoiceOS/architecture/pull/9) | + +### Bus stack — how components talk + +| ID | Document | Version | Status | +|----|----------|---------|--------| +| OVOS-MSG-1 | [Bus Message](message-object.md) | 2 | Draft | +| OVOS-SESSION-1 | [Session Carrier Wire Shape](session.md) | 1 | Draft | +| OVOS-SESSION-2 | [Session Lifecycle and State Ownership](session-lifecycle.md) | 1 | Draft | + +### Orchestrator stack — what processes utterances + +| ID | Document | Version | Status | +|----|----------|---------|--------| +| OVOS-PIPELINE-1 | [Utterance Lifecycle and Pipeline](pipeline.md) | 2 | Draft | +| OVOS-TRANSFORM-1 | [Transformer Plugins](transformer.md) | 1 | [Draft — in review (PR #20)](https://github.com/OpenVoiceOS/architecture/pull/20) | +| OVOS-CONTEXT-1 | [Intent Context](intent-context.md) | 1 | [Draft — in review (PR #18)](https://github.com/OpenVoiceOS/architecture/pull/18) | +| OVOS-CONVERSE-1 | [Active Handlers and Interactive Response](converse.md) | 1 | [Draft — in review (PR #25)](https://github.com/OpenVoiceOS/architecture/pull/25) | Each spec carries its own scope statement, design rationale, and -conformance section in its own header. Open the document for the -full picture — the table above is just an index. - -**Reading order.** The intent specs are numbered in dependency -order: OVOS-INTENT-1 defines the template grammar; OVOS-INTENT-2 -builds on it to define the resource files; OVOS-INTENT-3 builds on -both to define what an intent is. OVOS-MSG-1 is the bus-layer -envelope and the routing / session model — independent of the -intent stack and readable at any point. +conformance section in its header. Open the document for the full +picture — the tables above are an index. + +**Reading order by role:** +- *Writing a skill?* INTENT-1 → INTENT-2 → INTENT-3. INTENT-4 only if you need the registration wire format. +- *Building a pipeline plugin?* PIPELINE-1, then SESSION-1 + SESSION-2, then the role spec (CONVERSE-1, CONTEXT-1, or TRANSFORM-1). +- *Building an orchestrator?* MSG-1 → SESSION-1 → SESSION-2 → PIPELINE-1, then INTENT-4, CONTEXT-1, CONVERSE-1, TRANSFORM-1. +- *Surveying the architecture?* [APPENDIX §1](APPENDIX.md) for the three-stack narrative. For background — design rationale, comparisons with other systems, the catalogue of known divergences from current code, and known