Codex/create blueprint catalog for prebuilt pipelines - #264
Merged
drdave-flexnetos merged 21 commits intoDec 6, 2025
Merged
Conversation
… schema docs Co-authored-by: FlexNetOS <211752339+FlexNetOS@users.noreply.github.com>
Co-authored-by: FlexNetOS <211752339+FlexNetOS@users.noreply.github.com>
Co-authored-by: FlexNetOS <211752339+FlexNetOS@users.noreply.github.com>
[WIP] WIP address feedback on catalogs and contribution guidance
…blueprints.md Co-authored-by: FlexNetOS <211752339+FlexNetOS@users.noreply.github.com>
[WIP] Address feedback on catalogs and contribution guidance
Fix documentation inconsistencies and add missing blueprint.yaml schema
Add blueprint.yaml schema documentation for third-party contributors
Standardize maintainer role terminology across contribution guides
No changes needed - spelling already correct in storage/analytics/README.md
…into copilot/sub-pr-27-df3e1826-f341-4edb-8702-fafa82b8bef2
…-4edb-8702-fafa82b8bef2 Add blueprint.yaml schema documentation to third-party contribution guide
Contributor
There was a problem hiding this comment.
Pull request overview
This PR creates a comprehensive blueprint catalog documentation by adding detailed schema definitions and examples for third-party blueprint contributions. It also standardizes maintainer terminology across community documentation.
Key Changes
- Added detailed
blueprint.yamlschema documentation with required/optional fields breakdown - Included two complete blueprint examples (CI/CD and Agent Swarm) demonstrating real-world usage
- Standardized terminology by changing "Marketplace maintainers" to "Workflow maintainers"
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/community/third-party-blueprints.md | Adds comprehensive blueprint schema documentation with examples, validation guidance, and schema reference sections. Contains duplication issues with three separate schema definitions. |
| docs/community/marketplace-contributions.md | Updates terminology from "Marketplace maintainers" to "Workflow maintainers" for consistency |
Comment on lines
+25
to
+296
| ## `blueprint.yaml` Schema | ||
|
|
||
| Each blueprint **must** include a `blueprint.yaml` file describing its metadata, configuration, and integration points. The expected schema is as follows: | ||
|
|
||
| ```yaml | ||
| # blueprint.yaml | ||
| name: <string> # Unique identifier for the blueprint (e.g., "ci_cd/continuous-assurance") | ||
| display_name: <string> # Human-readable name for UI display | ||
| description: <string> # Brief summary of the blueprint's purpose | ||
| category: <string> # Category (e.g., "CI/CD", "Data Processing", "Agent Swarms") | ||
| version: <string> # Semantic version (e.g., "1.0.0") | ||
| authors: | ||
| - name: <string> | ||
| contact: <string> # (optional) Email or handle | ||
| inputs: | ||
| - key: <string> # Input parameter name | ||
| type: <string> # Data type (e.g., string, int, bool, enum) | ||
| required: <bool> | ||
| description: <string> | ||
| dependencies: | ||
| - <string> # List of required external systems or services | ||
| kernel_hooks: | ||
| - <string> # List of kernel hook identifiers (see examples in workflow/blueprints/README.md) | ||
| ui_affordances: | ||
| - <string> # List of UI features or surfaces provided | ||
| ``` | ||
|
|
||
| For complete examples, refer to the [Blueprint Catalog](../../workflow/blueprints/README.md). | ||
|
|
||
| ## Review Process | ||
|
|
||
| - **Intake:** Submit a merge request adding your blueprint entry under `workflow/blueprints/<slug>` with manifest and assets. | ||
| - **Automated Checks:** Kernel CI validates manifest schema, test evidence, security scans, and UI descriptors. | ||
| - **Human Review:** Workflow maintainers verify design, telemetry quality, and compliance posture within five business days. | ||
| - **Human Review:** Blueprint maintainers verify design, telemetry quality, and compliance posture within five business days. | ||
| - **Publication:** Approved blueprints receive a kernel-signed catalog entry and are surfaced in the UI with the `Third-Party` badge. | ||
|
|
||
| ## Blueprint Manifest Schema | ||
|
|
||
| Each blueprint submission **must** include a `blueprint.yaml` file describing its metadata, configuration, and integration points. The expected schema is as follows: | ||
|
|
||
| ```yaml | ||
| # blueprint.yaml | ||
| name: <string> # Unique identifier for the blueprint (e.g., "ci_cd/continuous-assurance") | ||
| display_name: <string> # Human-readable name for UI display | ||
| description: <string> # Brief summary of the blueprint's purpose | ||
| category: <string> # Category (e.g., "CI/CD", "Data Processing", "Agent Swarms") | ||
| version: <string> # Semantic version (e.g., "1.0.0") | ||
| authors: | ||
| - name: <string> | ||
| contact: <string> # (optional) Email or handle | ||
| inputs: | ||
| - key: <string> # Input parameter name | ||
| type: <string> # Data type (e.g., string, int, bool, enum) | ||
| required: <bool> | ||
| description: <string> | ||
| dependencies: | ||
| - <string> # List of required external systems or services | ||
| kernel_hooks: | ||
| - <string> # List of kernel hook identifiers | ||
| ui_affordances: | ||
| - <string> # List of UI features or surfaces provided | ||
| ``` | ||
|
|
||
| **Example:** | ||
|
|
||
| ```yaml | ||
| # blueprint.yaml | ||
| name: monitoring/observability-stack | ||
| display_name: Observability Stack Blueprint | ||
| description: Comprehensive monitoring and alerting pipeline with dashboards and SLO tracking | ||
| category: Monitoring | ||
| version: 1.2.0 | ||
| authors: | ||
| - name: Acme Monitoring Inc. | ||
| contact: support@acme-monitoring.io | ||
| inputs: | ||
| - key: retention_days | ||
| type: int | ||
| required: true | ||
| description: Number of days to retain metrics and logs | ||
| - key: alert_channels | ||
| type: enum | ||
| required: false | ||
| description: Notification channels for critical alerts (slack, email, pagerduty) | ||
| dependencies: | ||
| - prometheus>=2.40 | ||
| - grafana>=9.0 | ||
| - alertmanager>=0.25 | ||
| kernel_hooks: | ||
| - metrics:scrape-targets | ||
| - alerts:routing-rules | ||
| - dashboards:template-loader | ||
| ui_affordances: | ||
| - Metrics explorer with query builder | ||
| - Alert management console | ||
| - SLO compliance tracker | ||
| ``` | ||
|
|
||
| For additional examples and detailed explanations of kernel hooks and UI affordances, refer to `workflow/blueprints/README.md`. | ||
|
|
||
| ## Maintenance Expectations | ||
|
|
||
| - Keep manifests and documentation current with each release; version mismatches trigger catalog quarantine. | ||
| - Respond to security advisories within 48 hours; unresolved issues may result in temporary suspension. | ||
| - Coordinate with the analytics team to map any new metrics into `storage/analytics` to preserve dashboard continuity. | ||
|
|
||
| ## Blueprint Schema | ||
|
|
||
| Each blueprint **must** include a `blueprint.yaml` file in its root directory that describes its metadata, configuration, and integration points. This manifest enables the Noa Ark kernel to validate, instantiate, and integrate your blueprint into the workflow ecosystem. | ||
|
|
||
| ### Required Fields | ||
|
|
||
| ```yaml | ||
| name: <string> # Unique identifier (e.g., "monitoring/observability-stack") | ||
| display_name: <string> # Human-readable name shown in UI | ||
| description: <string> # Brief summary (1-2 sentences) of blueprint purpose | ||
| category: <string> # Category: "CI/CD", "Data Processing", "Agent Swarms", | ||
| # "Monitoring", "Security", or "Integration" | ||
| version: <string> # Semantic version (e.g., "1.0.0") | ||
| ``` | ||
|
|
||
| ### Optional Fields | ||
|
|
||
| ```yaml | ||
| authors: # List of blueprint authors | ||
| - name: <string> # Author name | ||
| contact: <string> # (optional) Email or handle | ||
|
|
||
| inputs: # Configuration parameters | ||
| - key: <string> # Parameter name (e.g., "api_endpoint") | ||
| type: <string> # Data type: "string", "int", "bool", "enum", "list" | ||
| required: <bool> # Whether this input is mandatory | ||
| default: <any> # (optional) Default value | ||
| description: <string> # User-facing description | ||
| enum: # (optional) Valid values for enum types | ||
| - <string> | ||
|
|
||
| dependencies: # External system requirements | ||
| - <string> # System name (e.g., "container-registry", "kafka-cluster") | ||
|
|
||
| kernel_hooks: # Kernel extension points | ||
| - <string> # Hook identifier (e.g., "build:containers", "deploy:progressive") | ||
|
|
||
| ui_affordances: # UI components provided | ||
| - <string> # UI surface (e.g., "dashboard:deployment-overview", | ||
| # "form:configuration", "tile:status") | ||
| ``` | ||
|
|
||
| ### Example: CI/CD Blueprint | ||
|
|
||
| ```yaml | ||
| # blueprint.yaml for ci_cd/continuous-assurance | ||
| name: "ci_cd/continuous-assurance" | ||
| display_name: "Continuous Assurance Pipeline" | ||
| description: "Enterprise CI/CD with risk-aware promotion, security scans, and rollback automation" | ||
| category: "CI/CD" | ||
| version: "1.2.0" | ||
|
|
||
| authors: | ||
| - name: "Noa Ark Platform Team" | ||
| contact: "platform@noaark.io" | ||
|
|
||
| inputs: | ||
| - key: "source_repo_url" | ||
| type: "string" | ||
| required: true | ||
| description: "Git repository URL for source code" | ||
|
|
||
| - key: "container_registry" | ||
| type: "string" | ||
| required: true | ||
| description: "Container registry endpoint (e.g., 'ghcr.io/org')" | ||
|
|
||
| - key: "deployment_strategy" | ||
| type: "enum" | ||
| required: false | ||
| default: "progressive" | ||
| description: "Deployment rollout strategy" | ||
| enum: | ||
| - "progressive" | ||
| - "blue-green" | ||
| - "canary" | ||
|
|
||
| - key: "enable_security_scan" | ||
| type: "bool" | ||
| required: false | ||
| default: true | ||
| description: "Run security vulnerability scans during build" | ||
|
|
||
| dependencies: | ||
| - "source-control" | ||
| - "container-registry" | ||
| - "crc-telemetry-stream" | ||
| - "notification-service" | ||
|
|
||
| kernel_hooks: | ||
| - "build:containers" | ||
| - "deploy:progressive" | ||
| - "notify:executive-brief" | ||
| - "rollback:automated" | ||
|
|
||
| ui_affordances: | ||
| - "dashboard:deployment-overview" | ||
| - "form:pipeline-configuration" | ||
| - "tile:release-status" | ||
| - "viewer:artifact-diff" | ||
| ``` | ||
|
|
||
| ### Example: Agent Swarm Blueprint | ||
|
|
||
| ```yaml | ||
| # blueprint.yaml for agents/swarm-field-kit | ||
| name: "agents/swarm-field-kit" | ||
| display_name: "Multi-Agent Swarm Kit" | ||
| description: "Bootstrap collaborative agent swarms with shared memory and coordinated execution" | ||
| category: "Agent Swarms" | ||
| version: "2.0.1" | ||
|
|
||
| authors: | ||
| - name: "Agent Systems Research" | ||
| contact: "agents@noaark.io" | ||
|
|
||
| inputs: | ||
| - key: "swarm_size" | ||
| type: "int" | ||
| required: true | ||
| description: "Number of agents in the swarm (2-50)" | ||
|
|
||
| - key: "memory_strategy" | ||
| type: "enum" | ||
| required: false | ||
| default: "episodic-sync" | ||
| description: "Shared memory synchronization approach" | ||
| enum: | ||
| - "episodic-sync" | ||
| - "distributed-cache" | ||
| - "event-sourcing" | ||
|
|
||
| - key: "agent_roles" | ||
| type: "list" | ||
| required: true | ||
| description: "List of agent role identifiers" | ||
|
|
||
| dependencies: | ||
| - "shared-memory-volume" | ||
| - "swarm-governance-policy" | ||
| - "secure-command-channel" | ||
|
|
||
| kernel_hooks: | ||
| - "swarm:manifest" | ||
| - "memory:episodic-sync" | ||
| - "telemetry:swarm-hivemind" | ||
| - "coordination:task-distribution" | ||
|
|
||
| ui_affordances: | ||
| - "dashboard:swarm-mission-control" | ||
| - "indicator:agent-health" | ||
| - "timeline:collaboration-events" | ||
| - "form:swarm-configuration" | ||
| ``` | ||
|
|
||
| ### Validation | ||
|
|
||
| The kernel CI pipeline automatically validates your `blueprint.yaml` against this schema during the review process. Common validation errors include: | ||
|
|
||
| - **Missing required fields**: Ensure `name`, `display_name`, `description`, `category`, and `version` are present | ||
| - **Invalid category**: Must be one of the defined categories | ||
| - **Malformed version**: Must follow semantic versioning (MAJOR.MINOR.PATCH) | ||
| - **Unknown kernel hooks**: Reference only documented kernel extension points | ||
| - **Type mismatches**: Input types must match supported values | ||
|
|
||
| For the complete list of available kernel hooks and UI affordances, see the [Blueprint Catalog](../../workflow/blueprints/README.md). |
There was a problem hiding this comment.
The document now contains three separate schema definitions with identical or overlapping content:
- "##
blueprint.yamlSchema" (lines 25-52) - "## Blueprint Manifest Schema" (lines 61-123)
- "## Blueprint Schema" (lines 131-296)
This creates significant duplication and maintenance burden. The schema should be documented in a single, comprehensive section. Consider consolidating these into one authoritative schema section, ideally the most detailed version (lines 131-296), and removing the duplicates.
| - **Intake:** Submit a merge request adding your blueprint entry under `workflow/blueprints/<slug>` with manifest and assets. | ||
| - **Automated Checks:** Kernel CI validates manifest schema, test evidence, security scans, and UI descriptors. | ||
| - **Human Review:** Workflow maintainers verify design, telemetry quality, and compliance posture within five business days. | ||
| - **Human Review:** Blueprint maintainers verify design, telemetry quality, and compliance posture within five business days. |
There was a problem hiding this comment.
Inconsistent terminology: Line 58 uses "Blueprint maintainers" while the original line 58 (in the context) used "Workflow maintainers". This change introduces an inconsistency, as line 22 in marketplace-contributions.md was changed from "Marketplace maintainers" to "Workflow maintainers" to establish consistency.
Consider using "Workflow maintainers" here as well to maintain consistent terminology across the documentation, or clarify if "Blueprint maintainers" represents a distinct team.
Suggested change
| - **Human Review:** Blueprint maintainers verify design, telemetry quality, and compliance posture within five business days. | |
| - **Human Review:** Workflow maintainers verify design, telemetry quality, and compliance posture within five business days. |
| - Provide a public Git repository or artifact bundle containing blueprint assets. | ||
| - Include `blueprint.yaml` detailing inputs, dependencies, kernel hooks, and UI affordances. | ||
| - Include `blueprint.yaml` detailing inputs, dependencies, kernel hooks, and UI affordances (see [Blueprint Schema](#blueprint-schema) below). | ||
| - Include `blueprint.yaml` detailing inputs, dependencies, kernel hooks, and UI affordances (see schema below). |
There was a problem hiding this comment.
Duplicate line: Line 10 duplicates the content from line 9. Both lines describe the same requirement for blueprint.yaml. The second instance should be removed.
One of these lines should be deleted to eliminate the duplication.
Suggested change
| - Include `blueprint.yaml` detailing inputs, dependencies, kernel hooks, and UI affordances (see schema below). |
Owner
Author
|
@copilot open a new pull request to apply changes based on the comments in this thread |
Contributor
|
@FlexNetOS I've opened a new pull request, #290, to work on those changes. Once the pull request is ready, I'll request review from you. |
drdave-flexnetos
deleted the
codex/create-blueprint-catalog-for-prebuilt-pipelines
branch
December 6, 2025 00:22
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.