Skip to content

4-Phase Activation Workflow

SCP uses a 4-phase workflow to take bundles from draft to deployed production systems.

Workflow Overview

Phase 1: Build → Phase 2: Validate → Phase 3: Deploy → Phase 4: Measure
 (DRAFT)        (VERSION)           (PUBLISH)        (MONITOR)

Current Status (v0.3.0)

Phase Status Description
Phase 1: Build ✅ Complete CLI tooling, templates, validation
Phase 2: Validate ✅ Complete Bundle registry, versioning
Phase 3: Deploy ✅ Complete Graph materialization, tag management
Phase 4: Measure ✅ Complete Context streaming, audit logging

All core functionality is operational. The v0.3.0 architecture adds graph-based dynamic context selection with agent authentication.

Phase 1: Build Bundles (DRAFT) ✅

Goal: Create bundles and SCDs from source materials

Workflow

  1. Gather source content - Documents, policies, knowledge, regulations
  2. Transpose to structured SCDs - Work with AI to convert unstructured → structured YAML
  3. Create SCD files - Write YAML files for each structured context document
  4. Create bundle manifests - Reference SCDs in bundle YAML files
  5. Iterate and refine - Review, improve, validate structure
  6. Keep version: "DRAFT" - Not locked yet, changes allowed

Validation Philosophy

Loose validation in Phase 1: - ✅ Validates YAML structure is well-formed - ✅ Validates required bundle fields exist - ✅ Validates bundle type constraints (e.g., concerns have empty imports) - ❌ Does NOT enforce required fields in SCD content

Why Loose? Supports spectrum from "paranoid CEO" (minimal disclosure) to "open CEO" (full transparency). Focus on structure, not content completeness.

Commands

# Create a bundle
scs bundle create

# Validate SCD structure
python -m scs_validator ./scds/my-scd.yaml

# Validate bundle structure
scs validate ./bundles/my-bundle.yaml

Status: ✅ Complete

  • ✅ CLI tooling with templates
  • ✅ SCD validator
  • ✅ Bundle validation (structure)
  • ✅ Healthcare, fintech, SaaS templates

Phase 2: Validate & Version ✅

Goal: Lock bundles with semantic versions, publish to registry

Workflow

  1. Run strict validation - Enforce all checks
  2. Fix validation errors - Address any issues found
  3. Version the bundle - Create immutable versioned bundle
  4. Publish to registry - Bundle available for deployment

Versioning Rules

Semantic Versioning (MAJOR.MINOR.PATCH): - MAJOR - Breaking changes (incompatible changes to SCDs) - MINOR - New features (add SCDs, non-breaking changes) - PATCH - Bug fixes (typos, clarifications)

Immutability: Once versioned and published, bundles CANNOT be changed.

Commands

# Version and lock
scs bundle version ./bundles/my-bundle.yaml --version 1.0.0

# Publish to registry (via API)
curl -X POST http://localhost:8000/api/bundles \
  -H "Content-Type: application/json" \
  -d @bundle.json

Status: ✅ Complete

  • ✅ Bundle registry API
  • ✅ Versioned bundle storage
  • ✅ Import resolution

Phase 3: Deploy ✅

Goal: Materialize bundles to graph, create tags for agent subscriptions

Workflow

  1. Materialize to graph - Bundle nodes, SCD nodes, relationships
  2. Create tags - Mutable pointers to immutable bundles (e.g., prior-auth:latest)
  3. Register agents - Agents with roles, allowed intents, API keys
  4. Configure policies - Agent-specific overrides and restrictions

Graph Materialization

When a bundle is deployed, it's materialized to the graph database:

Bundle Node ──CONTAINS──► SCD Nodes
                              │
                         APPLIES_TO
                              │
                              ▼
                         Role Nodes

Relationships preserved: - CONTAINS - Bundle contains SCDs - IMPORTS - Bundle imports another bundle - APPLIES_TO - SCD applies to role - GOVERNED_BY - SCD governed by another SCD - REFERENCES - SCD references another SCD

Tag Management

Tags are mutable pointers to immutable bundles:

# Create tag
curl -X POST http://localhost:8000/api/tags \
  -H "Content-Type: application/json" \
  -d '{"tag": "prior-auth:latest", "bundle_id": "bundle:prior-auth:1.0.0"}'

# Update tag (zero-downtime update for all agents)
curl -X PUT http://localhost:8000/api/tags/prior-auth:latest \
  -H "Content-Type: application/json" \
  -d '{"bundle_id": "bundle:prior-auth:1.1.0"}'

Agent Registration

# Register agent
curl -X POST http://localhost:8000/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent:prior-auth-prod",
    "name": "Prior Auth Production Agent",
    "role_id": "role:prior-auth-agent",
    "allowed_intents": ["prior_auth_check", "formulary_lookup"]
  }'

# Generate API key
curl -X POST http://localhost:8000/api/agents/agent:prior-auth-prod/api-keys

Status: ✅ Complete

  • ✅ Graph database (Apache AGE)
  • ✅ Bundle materialization
  • ✅ Tag management
  • ✅ Agent registry
  • ✅ API key authentication

Phase 4: Measure & Iterate ✅

Goal: Stream context to agents, track usage, audit everything

Context Request Flow (v0.3)

Agent Request → Auth → Intent Check → Graph Query → Policy Filter → Stream
  1. Agent authenticates with API key
  2. Intent validated against allowed_intents
  3. Graph queried for role-appropriate SCDs
  4. Policy applied (agent overrides/restrictions)
  5. Context streamed to agent
  6. Request logged for audit

API Integration

REST API: 

import httpx

response = httpx.post(
    "http://localhost:8000/api/context",
    headers={"X-API-Key": api_key},
    json={"task_type": "prior_auth_check"}
)

context = response.json()
# Use context["scd_ids"] and context["scd_content"]

gRPC Streaming: 

from context_service.context_service_pb2 import ContextRequest
from context_service.context_service_pb2_grpc import ContextServiceStub

request = ContextRequest(
    api_key=api_key,
    task_type="prior_auth_check"
)
response = await stub.RequestContext(request)

Audit Trail

Every context request is logged: - Agent ID, Role ID - Task type, Parameters - SCDs returned - Timestamp, Processing time

SELECT * FROM agent_context_requests
WHERE agent_id = 'agent:prior-auth-prod'
ORDER BY requested_at DESC;

Metrics Available

  • Usage: Which agents, which tasks, which SCDs
  • Performance: Processing time, success rate
  • Security: Failed auth attempts, unauthorized intents

Status: ✅ Complete

  • ✅ REST API for context requests
  • ✅ gRPC streaming
  • ✅ Role-based context selection
  • ✅ Policy filtering (overrides/restrictions)
  • ✅ Full audit logging
  • ✅ 13/13 integration tests passing

v0.2 vs v0.3 Flow

Aspect v0.2 (Tag-based) v0.3 (Intent-based)
Authentication Token in request API key header
Selection Flatten entire bundle graph Graph traversal by role
Filtering None (get everything) Role-based + agent policy
Streaming Continuous updates Request/response
Use Case Design-time (full context) Runtime (minimal governance)

Both modes are supported: - v0.2 Subscribe: For dev agents that need full context - v0.3 RequestContext: For production agents that need minimal governance context

Phase Summary

Phase What Happens Tools
1: Build Create bundles and SCDs CLI (scs bundle create, scs validate)
2: Validate Version and publish to registry API (POST /api/bundles)
3: Deploy Materialize to graph, register agents API (POST /api/agents, graph seeding)
4: Measure Stream context, audit requests API (POST /api/context), gRPC

Planned Enhancements

The following features are on the roadmap for future releases:

  • Production authentication (OAuth2/OIDC)
  • Multi-tenancy with organization isolation
  • Adherence measurement and drift detection
  • Dashboards and analytics UI
  • CLI deploy command

Next Steps