Template DSL Specification (N1 + N2)¶
Version: 1.0.0 Status: Ratified Author: GO Date: 2026-03-30 Scope: XIOPro project template authoring, registry, and runtime evaluation
1. Purpose¶
This specification defines the formal YAML schema for XIOPro project templates (N1) and the versioning and registry lifecycle for those templates (N2).
A template is a machine-readable description of a project lifecycle. It encodes: - The stages a project passes through - The steps within each stage - The gate criteria that must be satisfied before progression - The agents assigned to each stage or step - The dependency constraints between stages and projects
Templates are the authoritative source of structure for any project spawned in XIOPro. The PO uses a template as its instruction set; the runtime uses the template's gates to enforce progression.
2. Schema Concepts¶
| Concept | Description |
|---|---|
| Template | Top-level document describing a project type |
| Stage | A named lifecycle phase (e.g., research, blueprint) |
| Step | A unit of work within a stage |
| Gate | Entry or exit checkpoint for a stage or step |
| Agent Role | A functional role label (e.g., researcher, architect) |
| Agent Definition | A contextual binding of an agent role to a concrete agent type |
| Dependency | A constraint requiring another stage or project to complete first |
3. Full Template Schema¶
# ─────────────────────────────────────────────
# TEMPLATE DSL — Full schema with annotations
# ─────────────────────────────────────────────
template:
# ── Metadata ──────────────────────────────────────────────────────────────
id: string # Globally unique slug. Lowercase, hyphens only.
# Example: "iso19650-it-project"
# REQUIRED.
name: string # Human-readable display name.
# Example: "ISO 19650 IT Project"
# REQUIRED.
version: semver # Semantic version of this template definition.
# Format: MAJOR.MINOR.PATCH
# Example: "2.1.0"
# REQUIRED.
domain: string # Domain or industry category.
# Example: "construction", "software", "marketing"
# REQUIRED.
author: string # Author identifier (agent ID or human).
# Example: "GO", "shai"
# REQUIRED.
description: string # One-paragraph explanation of when to use this template.
# OPTIONAL.
lifecycle_status: enum # Current status in the template lifecycle.
# Values: draft | active | deprecated | archived
# REQUIRED. New templates start at "draft".
created_at: iso8601 # Timestamp of first registration.
# Example: "2026-03-30T09:00:00Z"
# Set by registry on first write; do not set manually.
updated_at: iso8601 # Timestamp of last modification.
# Managed by registry. Do not set manually.
extends: string | null # Template ID this template inherits from.
# Null = no inheritance.
# Example: "base-it-project"
# See Section 7 (Template Inheritance).
tags: list[string] # Arbitrary classification tags.
# Example: ["iso19650", "bim", "regulated"]
# OPTIONAL.
# ── Agent Role Assignments ─────────────────────────────────────────────────
# Maps abstract role labels to concrete agent types.
# These are the defaults for the whole template; stages and steps can override.
agent_roles:
researcher: "IO:shai | Specialist:researcher"
# ^ Role label : agent_id pattern or literal agent type
# Accepts exact actor IDs ("IO:shai"), type patterns ("Specialist:researcher"),
# or pipe-separated fallback chain evaluated left-to-right.
architect: "Specialist:architect"
reviewer: "PO" # PO performs all review steps by default
executor: "Worker" # Ephemeral Worker spawned for execution steps
auditor: "GO" # GO performs gate audits
# ── Contextual Agent Definitions ──────────────────────────────────────────
# Full definition of each agent type used in this template.
# Provides spawn parameters, capability constraints, and resource limits.
agent_definitions:
- role: researcher
spawn_mode: "on_demand" # on_demand | persistent | inherited
model: "sonnet" # sonnet | haiku | opus (per ticket or override)
max_concurrent: 3
tools_allowed:
- Read
- Grep
- Glob
- WebSearch
capabilities:
- domain_research
- literature_review
- gap_analysis
resource_limit:
token_budget_per_step: 50000
wall_clock_minutes: 60
- role: architect
spawn_mode: "on_demand"
model: "sonnet"
max_concurrent: 1
tools_allowed:
- Read
- Grep
- Glob
- Write
- Edit
capabilities:
- system_design
- schema_design
- dependency_analysis
- role: executor
spawn_mode: "on_demand"
model: "sonnet"
max_concurrent: 5
tools_allowed:
- Read
- Grep
- Glob
- Write
- Edit
- Bash
capabilities:
- code_implementation
- test_execution
- deployment
- role: reviewer
spawn_mode: "persistent" # PO is always running; no extra spawn needed
model: "sonnet"
max_concurrent: 1
tools_allowed:
- Read
- Grep
- Glob
capabilities:
- gate_evaluation
- quality_review
- approval_decision
# ── Stages ────────────────────────────────────────────────────────────────
stages:
- name: research # Stage identifier. Lowercase, underscores.
# REQUIRED.
display_name: "Research" # UI label. OPTIONAL; defaults to capitalized name.
description: >
Gather domain context, constraints, prior art, and external references
relevant to the project.
entry_gate: # Conditions required BEFORE this stage begins.
criteria:
- "previous stage 'idea' must have status: completed"
- "project.scope_statement is not null"
required_approvals: [] # Empty = no human approval needed to enter
automated_checks:
- type: field_not_null
field: "project.scope_statement"
- type: stage_completed
stage: "idea"
exit_gate: # Conditions required to LEAVE this stage.
criteria:
- "at least 3 research steps must have status: verified"
- "research_memo artifact must exist"
- "no open step has status: failed"
required_approvals:
- actor: "PO"
reason: "PO must confirm research is sufficient before brainstorm"
automated_checks:
- type: min_steps_verified
count: 3
- type: artifact_exists
artifact_type: "research_memo"
- type: no_failed_steps
agent_role: researcher # Default agent role for steps in this stage.
# Steps can override.
steps:
- name: domain_literature_review
display_name: "Domain Literature Review"
description: "Survey existing standards, frameworks, and publications."
agent_role: researcher # Inherits stage default; explicit here for clarity.
inputs:
- key: scope_statement
source: "project.scope_statement"
required: true
- key: domain
source: "project.domain"
required: true
outputs:
- key: literature_summary
type: artifact
artifact_type: research_memo
required: true
- key: source_list
type: artifact
artifact_type: reference_list
required: true
verification:
method: "peer_review" # peer_review | automated | self | human
reviewer_role: reviewer
criteria:
- "summary covers at least 5 distinct sources"
- "no hallucinated citations (URLs or ISBNs must resolve)"
depends_on: [] # No intra-stage dependency; starts immediately.
- name: gap_analysis
display_name: "Gap Analysis"
description: "Identify what is unknown or unresolved after literature review."
agent_role: researcher
inputs:
- key: literature_summary
source: "step:domain_literature_review.literature_summary"
required: true
outputs:
- key: gap_report
type: artifact
artifact_type: gap_analysis_memo
required: true
verification:
method: "peer_review"
reviewer_role: reviewer
criteria:
- "gap report identifies at least 3 open questions"
depends_on:
- step: domain_literature_review
status: verified # Must be verified, not just completed
- name: constraint_mapping
display_name: "Constraint Mapping"
description: "Document regulatory, budget, and timeline constraints."
agent_role: researcher
inputs:
- key: project_brief
source: "project.brief"
required: false
outputs:
- key: constraint_register
type: artifact
artifact_type: constraint_register
required: true
verification:
method: "human"
reviewer_role: "IO:shai"
criteria:
- "budget ceiling confirmed by Shai"
- "regulatory requirements listed and tagged"
depends_on: []
- name: blueprint
display_name: "Blueprint"
description: >
Full technical design: architecture, ODM schema, agent topology,
infrastructure, and governance decisions.
entry_gate:
criteria:
- "stage 'manifest' must have status: completed"
- "manifest artifact must exist"
- "human approval from IO:shai required for blueprint entry"
required_approvals:
- actor: "IO:shai"
reason: "Shai must approve scope before blueprint investment"
automated_checks:
- type: stage_completed
stage: manifest
- type: artifact_exists
artifact_type: manifest
exit_gate:
criteria:
- "all blueprint steps must have status: verified"
- "system_review artifact must exist"
- "no unresolved design decision with priority: critical"
required_approvals:
- actor: "PO"
reason: "PO signs off on blueprint completeness"
- actor: "GO"
reason: "GO audits resource estimates"
automated_checks:
- type: all_steps_verified
- type: artifact_exists
artifact_type: system_review
- type: no_open_decisions
priority: critical
agent_role: architect
steps:
- name: architecture_design
display_name: "Architecture Design"
agent_role: architect
inputs:
- key: manifest
source: "stage:manifest.manifest_artifact"
required: true
outputs:
- key: architecture_doc
type: artifact
artifact_type: architecture_document
required: true
verification:
method: "peer_review"
reviewer_role: reviewer
criteria:
- "all system components named and described"
- "integration points documented"
- "no single point of failure unaddressed"
depends_on: []
- name: odm_schema_design
display_name: "ODM Schema Design"
agent_role: architect
inputs:
- key: architecture_doc
source: "step:architecture_design.architecture_doc"
required: true
outputs:
- key: odm_schema
type: artifact
artifact_type: schema_document
required: true
verification:
method: "automated"
criteria:
- "schema parses as valid SQL or YAML"
- "all FK relationships resolve"
depends_on:
- step: architecture_design
status: verified
- name: execute
display_name: "Execute"
description: "Implementation, testing, and deployment."
entry_gate:
criteria:
- "stage 'work_plan' must have status: completed"
- "stage 'test_plan' must have status: completed"
required_approvals:
- actor: "IO:shai"
reason: "Human go/no-go before execution"
automated_checks:
- type: stage_completed
stage: work_plan
- type: stage_completed
stage: test_plan
exit_gate:
criteria:
- "all tickets in sprint have status: done"
- "acceptance_test artifact must have status: passed"
- "no open incident with severity: critical"
required_approvals:
- actor: "GO"
reason: "GO confirms delivery before project closes"
automated_checks:
- type: all_tickets_done
- type: artifact_status
artifact_type: acceptance_test
expected_status: passed
- type: no_open_incidents
severity: critical
agent_role: executor
steps:
- name: implementation
display_name: "Implementation"
agent_role: executor
inputs:
- key: work_plan
source: "stage:work_plan.work_plan_artifact"
required: true
- key: architecture_doc
source: "stage:blueprint.architecture_doc"
required: true
outputs:
- key: implementation_commit
type: git_ref
required: true
verification:
method: "automated"
criteria:
- "CI pipeline passes"
- "no critical security findings"
depends_on: []
- name: acceptance_testing
display_name: "Acceptance Testing"
agent_role: executor
inputs:
- key: implementation_commit
source: "step:implementation.implementation_commit"
required: true
- key: test_plan
source: "stage:test_plan.test_plan_artifact"
required: true
outputs:
- key: acceptance_test
type: artifact
artifact_type: acceptance_test
required: true
verification:
method: "human"
reviewer_role: "IO:shai"
criteria:
- "all acceptance criteria from manifest confirmed by Shai"
depends_on:
- step: implementation
status: verified
# ── Dependency Constraints ─────────────────────────────────────────────────
# Stage-level sequencing. Defines which stage must complete before another can start.
# Steps within a stage use the per-step `depends_on` field above.
stage_dependencies:
- stage: research
depends_on: null # First stage; no dependency
- stage: brainstorm
depends_on:
stage: research
status: completed # completed | verified | approved
- stage: manifest
depends_on:
stage: brainstorm
status: completed
- stage: blueprint
depends_on:
stage: manifest
status: approved # Requires human approval gate
- stage: work_plan
depends_on:
stage: blueprint
status: approved
- stage: test_plan
depends_on:
stage: blueprint
status: approved # Parallel with work_plan
- stage: review
depends_on:
stage: test_plan
status: completed
- stage: execute
depends_on:
stage: review
status: approved
# ── Validation Rules ───────────────────────────────────────────────────────
# Declarative rules that must be satisfied for a template to be considered valid.
# The registry validates these rules before accepting a new or updated template.
validation_rules:
- id: unique_stage_names
description: "All stage names within a template must be unique."
check: "count(stages[*].name) == count(distinct stages[*].name)"
severity: error
- id: unique_step_names_per_stage
description: "All step names within a single stage must be unique."
check: "for each stage: count(steps[*].name) == count(distinct steps[*].name)"
severity: error
- id: entry_gate_required
description: "Every stage except the first must have an entry_gate."
check: "for stages[1:]: entry_gate is not null"
severity: error
- id: exit_gate_required
description: "Every stage except the last must have an exit_gate."
check: "for stages[:-1]: exit_gate is not null"
severity: error
- id: step_outputs_defined
description: "Every step must declare at least one required output."
check: "for each step: count(outputs where required=true) >= 1"
severity: error
- id: depends_on_resolves
description: "Every depends_on reference must point to an existing stage or step name."
check: "for each depends_on.stage: value exists in stages[*].name"
severity: error
- id: agent_role_defined
description: "Every agent_role referenced in a stage or step must be declared in agent_roles."
check: "all role references exist in agent_roles keys"
severity: error
- id: agent_definition_for_role
description: "Every agent_role key must have a corresponding entry in agent_definitions."
check: "agent_roles.keys() == agent_definitions[*].role"
severity: warning
- id: semver_format
description: "Template version must conform to MAJOR.MINOR.PATCH format."
check: "version matches /^\\d+\\.\\d+\\.\\d+$/"
severity: error
- id: valid_lifecycle_status
description: "lifecycle_status must be one of: draft, active, deprecated, archived."
check: "lifecycle_status in [draft, active, deprecated, archived]"
severity: error
- id: extends_chain_depth
description: "Template inheritance must not exceed 3 levels deep."
check: "depth(extends chain) <= 3"
severity: error
- id: no_circular_extends
description: "A template must not extend itself directly or transitively."
check: "no cycle in extends graph"
severity: error
- id: id_format
description: "Template ID must be lowercase alphanumeric with hyphens only."
check: "id matches /^[a-z0-9][a-z0-9-]*[a-z0-9]$/"
severity: error
4. Minimal Valid Template Example¶
A minimal template passes all validation rules with the least required fields. Use this as a starting skeleton.
template:
id: content-creation-basic
name: "Content Creation (Basic)"
version: "1.0.0"
domain: content
author: GO
lifecycle_status: draft
extends: null
agent_roles:
executor: "Worker"
reviewer: "PO"
agent_definitions:
- role: executor
spawn_mode: on_demand
model: sonnet
max_concurrent: 3
tools_allowed: [Read, Grep, Glob, Write, Edit]
capabilities: [writing, editing]
- role: reviewer
spawn_mode: persistent
model: sonnet
max_concurrent: 1
tools_allowed: [Read, Grep, Glob]
capabilities: [gate_evaluation, quality_review]
stages:
- name: ideate
display_name: "Ideate"
entry_gate: null # First stage — no entry gate required
exit_gate:
criteria:
- "artifact 'brief' must exist"
required_approvals: []
automated_checks:
- type: artifact_exists
artifact_type: brief
agent_role: executor
steps:
- name: draft_brief
display_name: "Draft Brief"
agent_role: executor
inputs:
- key: topic
source: "project.topic"
required: true
outputs:
- key: brief
type: artifact
artifact_type: brief
required: true
verification:
method: self
criteria:
- "brief is at least 200 words"
depends_on: []
- name: produce
display_name: "Produce"
entry_gate:
criteria:
- "stage 'ideate' must have status: completed"
required_approvals: []
automated_checks:
- type: stage_completed
stage: ideate
exit_gate:
criteria:
- "artifact 'deliverable' must exist"
- "all steps verified"
required_approvals:
- actor: PO
reason: "PO confirms deliverable quality"
automated_checks:
- type: artifact_exists
artifact_type: deliverable
- type: all_steps_verified
agent_role: executor
steps:
- name: write_content
display_name: "Write Content"
agent_role: executor
inputs:
- key: brief
source: "stage:ideate.brief"
required: true
outputs:
- key: deliverable
type: artifact
artifact_type: deliverable
required: true
verification:
method: peer_review
reviewer_role: reviewer
criteria:
- "content matches brief requirements"
- "no factual errors"
depends_on: []
stage_dependencies:
- stage: ideate
depends_on: null
- stage: produce
depends_on:
stage: ideate
status: completed
validation_rules: [] # Inherits global ruleset from registry
5. Template Inheritance¶
A template may extend a parent template to reuse its stage structure, agent definitions, and validation rules.
5.1 Inheritance Rules¶
extendsreferences theidof another template in the registry.- The child template inherits all stages, steps, agent_roles, agent_definitions, stage_dependencies, and validation_rules from the parent.
- The child may:
- Override an inherited stage by redefining it with the same
name. The child's definition replaces the parent's entirely. - Add new stages not present in the parent. New stages must declare their own
stage_dependenciesentries. - Remove inherited stages by listing them in
omit_stages. - Override individual steps within an inherited stage using the same step
name. - Maximum inheritance depth: 3 levels.
- Circular inheritance is forbidden.
5.2 Inheritance Example¶
# Parent template (base-it-project v2.0.0)
template:
id: base-it-project
name: "Base IT Project"
version: "2.0.0"
lifecycle_status: active
stages:
- name: research
# ... (full definition)
- name: blueprint
# ... (full definition)
- name: execute
# ... (full definition)
# Child template — ISO 19650 IT Project
template:
id: iso19650-it-project
name: "ISO 19650 IT Project"
version: "1.0.0"
domain: construction
author: GO
lifecycle_status: draft
extends: base-it-project # Inherits all stages from base-it-project
# Only define what differs from the parent:
omit_stages: [] # No stages removed
stages:
# Override the research stage to add ISO 19650-specific steps
- name: research
display_name: "Research (ISO 19650)"
entry_gate: # Override entry gate
criteria:
- "EIR document must be provided"
required_approvals: []
automated_checks:
- type: artifact_exists
artifact_type: eir
exit_gate:
criteria:
- "BIM Execution Plan draft must exist"
- "at least 5 research steps verified"
required_approvals:
- actor: PO
reason: "PO confirms ISO 19650 research coverage"
automated_checks:
- type: artifact_exists
artifact_type: bim_execution_plan_draft
agent_role: researcher
steps:
# All parent steps are inherited plus these additions:
- name: eir_analysis
display_name: "EIR Analysis"
agent_role: researcher
inputs:
- key: eir
source: "project.eir_document"
required: true
outputs:
- key: eir_summary
type: artifact
artifact_type: eir_summary
required: true
verification:
method: peer_review
reviewer_role: reviewer
criteria:
- "all EIR requirements extracted and tagged"
depends_on: []
6. Gate Definitions Reference¶
Gates are declared inline within stages (see schema above). This section defines the full type vocabulary for automated_checks.
automated_checks:
# Stage progression checks
- type: stage_completed
stage: <stage_name> # Named stage must have status: completed
- type: stage_status
stage: <stage_name>
expected_status: <status> # completed | verified | approved
# Step checks
- type: all_steps_verified
# All steps in the current stage must have status: verified
- type: min_steps_verified
count: <integer> # At least N steps must be verified
- type: no_failed_steps
# No step in the current stage may have status: failed
# Artifact checks
- type: artifact_exists
artifact_type: <type> # An artifact of this type must exist
- type: artifact_status
artifact_type: <type>
expected_status: <status> # Artifact must have the specified status
# Field checks
- type: field_not_null
field: <dot.path.to.field> # Field in project or stage context must not be null
- type: field_matches
field: <dot.path.to.field>
pattern: <regex> # Field must match the regex
# Ticket checks
- type: all_tickets_done
# All sprint tickets linked to this stage must have status: done
- type: max_open_tickets
count: <integer> # At most N tickets may remain open
# Incident checks
- type: no_open_incidents
severity: <critical|high|medium> # No open incidents at or above this severity
# Decision checks
- type: no_open_decisions
priority: <critical|high> # No unresolved decisions at or above this priority
# Custom (escape hatch)
- type: custom
rule_id: <rule_id> # Reference to a rule defined in validation_rules
parameters:
key: value
7. Template Registry and Versioning (N2)¶
7.1 Registry Location¶
Templates are registered in:
The registry is the single source of truth for all available templates.
7.2 Registry Schema¶
# template_registry.yaml
registry_version: "1.0"
last_updated: "2026-03-30T09:00:00Z"
templates:
- id: base-it-project
name: "Base IT Project"
current_version: "2.1.0"
lifecycle_status: active
versions:
- version: "1.0.0"
status: archived
registered_at: "2026-01-15T10:00:00Z"
breaking_changes: false
migration_from: null
file: "templates/base-it-project/v1.0.0.yaml"
- version: "2.0.0"
status: deprecated
registered_at: "2026-02-20T14:00:00Z"
breaking_changes: true
migration_from: "1.0.0"
migration_path: "templates/base-it-project/MIGRATION_1x_to_2x.md"
file: "templates/base-it-project/v2.0.0.yaml"
- version: "2.1.0"
status: active
registered_at: "2026-03-25T09:00:00Z"
breaking_changes: false
migration_from: "2.0.0"
migration_path: null # Non-breaking; no migration needed
file: "templates/base-it-project/v2.1.0.yaml"
changelog:
"2.1.0": "Added gap_analysis step to research stage. No breaking changes."
"2.0.0": "Replaced manual_review step with automated gate check. Breaking: removed 'approver_list' field."
"1.0.0": "Initial version."
- id: iso19650-it-project
name: "ISO 19650 IT Project"
current_version: "1.0.0"
lifecycle_status: draft
extends: base-it-project
versions:
- version: "1.0.0"
status: draft
registered_at: "2026-03-30T09:00:00Z"
breaking_changes: false
migration_from: null
file: "templates/iso19650-it-project/v1.0.0.yaml"
changelog:
"1.0.0": "Initial ISO 19650 domain extension of base-it-project."
7.3 Semantic Versioning Rules¶
All template versions use Semantic Versioning (MAJOR.MINOR.PATCH):
| Change Type | Version Increment | Breaking? | Migration Required? |
|---|---|---|---|
| Rename or remove a stage | MAJOR | Yes | Yes |
| Rename or remove a step | MAJOR | Yes | Yes |
| Remove a required field from a gate or step | MAJOR | Yes | Yes |
| Change a required approval actor | MAJOR | Yes | Yes |
| Add a new required step to an existing stage | MAJOR | Yes | Yes |
| Add a new optional step or stage | MINOR | No | No |
| Add a new optional field to a gate or step | MINOR | No | No |
| Add a new agent_definition entry | MINOR | No | No |
| Update description text only | PATCH | No | No |
| Fix a validation rule check expression | PATCH | No | No |
| Update resource limits | PATCH | No | No |
Rule: When in doubt, increment MAJOR. It is safer to over-declare a breaking change than to silently break running projects.
7.4 Lifecycle Status Transitions¶
draft → active → deprecated → archived
↑_____________________________|
(re-activation from archived is not permitted without a new version registration)
| Status | Meaning | Permitted Operations |
|---|---|---|
draft |
In development, not for production use | Any modification; not assigned to new projects |
active |
Production-ready; assignable to new projects | PATCH and MINOR updates only without version bump; MAJOR requires new version |
deprecated |
Still runs existing projects; no new assignments | Bug-fix PATCH updates only; new projects redirected to successor |
archived |
Frozen; read-only | No modifications; existing projects must migrate before archiving |
Transition rules:
- draft → active: Requires all validation_rules to pass; PO must approve.
- active → deprecated: GO sets this when a newer MAJOR version is active; requires migration_path to be documented.
- deprecated → archived: All projects using this template version must have migrated or been closed. GO performs this transition.
- active → archived (direct): Only permitted if no projects are using this version.
7.5 Migration Paths¶
When a MAJOR version is released, the author must provide a migration document:
The migration document must specify:
- What changed: List every breaking change with before/after examples.
- Impact assessment: Which project types or phases are affected.
- Migration steps: Step-by-step instructions for updating a live project to the new template version.
- Rollback: How to revert if the migration fails.
- Deadline: When the old version transitions from
deprecatedtoarchived.
Migration example:
# Migration Guide: base-it-project v1.x → v2.x
## Breaking Changes
### 1. `approver_list` field removed from exit gates
**Before (v1.x):**
exit_gate:
approver_list: ["IO:shai", "PO"]
**After (v2.x):**
exit_gate:
required_approvals:
- actor: "IO:shai"
reason: "..."
- actor: "PO"
reason: "..."
**Action:** Replace all `approver_list` fields with `required_approvals` array.
### 2. `manual_review` step replaced by automated gate check
**Before (v1.x):** Each stage had an explicit `manual_review` step as the last step.
**After (v2.x):** The `exit_gate.required_approvals` field handles human approval.
Remove any step named `manual_review` from all templates extending v1.x.
## Impact
- Projects in `execute` stage with a `manual_review` step in progress:
Complete the current step, then apply migration before starting the next stage.
- Projects not yet started: Apply migration before spawning PO.
## Migration Steps
1. Open the project template YAML.
2. Replace `approver_list` with `required_approvals` per the schema above.
3. Remove any `manual_review` steps from all stages.
4. Run `template validate --id <template-id> --version 2.0.0` to confirm.
5. Update `template_registry.yaml` to set current_version to "2.0.0".
6. Notify GO via bus message `template.migrated` with the project ID.
## Rollback
Revert the YAML file to the v1.x snapshot in git. Set registry back to version "1.0.0".
## Deadline
base-it-project v1.x transitions to `archived` on 2026-05-01.
All projects must migrate before that date.
7.6 Registry Operations¶
| Operation | Actor | Trigger |
|---|---|---|
| Register new template | GO / PO | Template Builder completes a new template |
Promote draft → active |
PO (with GO audit) | Validation passes + review approved |
| Publish MINOR update | GO | No approval required |
| Publish MAJOR update | GO | Migration doc required; PO approval required |
| Deprecate a version | GO | Newer MAJOR version goes active |
| Archive a version | GO | All projects migrated or closed |
8. Validation at Runtime¶
When the runtime (PO or registry) validates a template, it executes the following checks in order:
- Parse check — YAML must be syntactically valid.
- Schema check — All REQUIRED fields must be present and correctly typed.
- Internal consistency — All validation_rules defined in Section 3 are evaluated.
- Inheritance resolution — If
extendsis set, the parent template is fetched from the registry and merged. The merged result is then re-validated against the schema. - Dependency graph — Stage and step dependencies are resolved. Cycles are detected and rejected.
- Agent role resolution — All role references resolve to declared
agent_roleskeys. - Registry uniqueness — No other template with the same
idandversionexists in the registry.
A template is valid if and only if all 7 checks pass with no error-severity findings.
warning-severity findings are logged but do not block registration.
9. Reference¶
| Item | Location |
|---|---|
| Template registry | ~/STRUXIO_Workspace/STRUXIO_OS/struxio-control/state/template_registry.yaml |
| Template YAML files | ~/STRUXIO_Workspace/STRUXIO_OS/struxio-control/state/templates/<id>/ |
| Migration docs | ~/STRUXIO_Workspace/STRUXIO_OS/struxio-control/state/templates/<id>/MIGRATION_*.md |
| Part 9 (template types) | BLUEPRINT_XIOPro_v5_Part9_Project_Templates.md |
| Part 4 (agent system) | BLUEPRINT_XIOPro_v5_Part4_Agent_System.md |
| Agent protocol spec | resources/SPEC_agent_protocol.md |
| Agent auth spec | resources/SPEC_agent_auth.md |