SCS Tools

Complete CLI toolkit for creating, managing, and validating Structured Context Specification (SCS) projects.

Overview

scs-tools provides everything you need to work with SCS projects:

• Scaffold new SCS projects with proper structure and templates
• Initialize SCS in existing projects
• Add SCDs and domain bundles incrementally
• Manage bundles and project configuration
• Validate SCDs and bundles against the specification

Do I Need Both Tools?

No - just install scs-tools.

The SCS ecosystem includes two packages:

• scs-tools (this package) - Full CLI toolkit for project management
• scs-validator (in scs-spec/tools/scd-validator) - Standalone validator

The scs-validator is included as a dependency of scs-tools, so installing scs-tools gives you everything. The standalone validator is only needed if you want validation without the project management features.

Installation

From PyPI (when published)

pip install scs-tools

This automatically installs scs-validator as a dependency.

From Source

# Clone the main repo
git clone https://github.com/tim-mccrimmon/scs-spec.git

# Navigate to scs-cli directory
cd scs-spec/../scs-cli

# Install in development mode
pip install -e .

For Development

cd scs-cli
pip install -e ".[dev]"

Commands

The scs command provides five main subcommands:

1. scs new - Create New Projects

Scaffold a complete SCS project from templates.

# Basic usage - creates standard project
scs new project my-project

# Healthcare application (HIPAA, CHAI, TEFCA)
scs new project medication-adherence --type healthcare

# Financial services (PCI-DSS, SOX)
scs new project banking-app --type fintech

# SaaS product (GDPR, SOC2)
scs new project my-saas --type saas

# Government application (NIST, FedRAMP)
scs new project gov-portal --type government

# Minimal project (11 essential SCDs)
scs new project prototype --type minimal

# Standard project (38 minimum SCDs)
scs new project my-app --type standard

Options:

# Specify output directory
scs new project my-app --dir /path/to/projects

# Add author information
scs new project my-app --author "Jane Doe" --email "jane@example.com"

# Interactive mode (prompts for all options)
scs new project my-app --interactive

2. scs init - Initialize Existing Projects

Add SCS structure to an existing project.

# Initialize in current directory
scs init

# Initialize with specific project type
scs init --type healthcare

# Initialize in specific directory
scs init --dir /path/to/existing/project

3. scs add - Add SCDs and Bundles

Incrementally add SCDs or domain bundles to your project.

# Add a specific SCD
scs add scd system-context

# Add a domain bundle
scs add bundle security

# Add multiple SCDs
scs add scd authn-authz data-protection threat-model

# Add domain bundle with all related SCDs
scs add bundle compliance-governance --with-scds

4. scs bundle - Manage Bundles

Create and manage SCD bundles.

# Create a bundle from SCDs
scs bundle create --name my-bundle --scds context/project/*.yaml

# List all bundles
scs bundle list

# Update a bundle
scs bundle update bundles/project-bundle.yaml

# Validate bundle completeness
scs bundle check bundles/project-bundle.yaml

5. scs validate - Validate SCDs and Bundles

Validate SCS documents against the specification. This command wraps the scs-validator tool.

# Validate a single SCD file
scs validate context/project/system-context.yaml

# Validate multiple SCD files
scs validate context/project/*.yaml

# Validate a bundle
scs validate --bundle bundles/project-bundle.yaml

# Strict mode (fail on warnings)
scs validate --bundle bundles/project-bundle.yaml --strict

# JSON output
scs validate --bundle bundles/project-bundle.yaml --output json

# Skip completeness checks
scs validate --bundle bundles/project-bundle.yaml --skip-completeness

Validation Options:

• --bundle - Validate a bundle file instead of individual SCDs
• --schema-dir - Specify custom schema directory
• --output [text|json] - Output format (default: text)
• --strict - Fail on warnings (exit code 2)
• --no-color - Disable colored output
• --verbose - Verbose output
• --skip-completeness - Skip Level 6 completeness validation

Note: The scs validate command uses the scs-validator package under the hood. For detailed validation documentation, see the SCS Validator README.

Help

Get help for any command:

scs --help
scs new --help
scs init --help
scs add --help
scs bundle --help
scs validate --help

Project Structure

A generated SCS project has this structure:

my-project/
├── bundles/                    # SCS bundles
│   ├── project-bundle.yaml    # Top-level bundle
│   ├── meta-bundle.yaml       # Meta vocabulary
│   ├── standards-bundle.yaml  # Compliance standards
│   └── domains/               # Domain bundles
│       ├── architecture.yaml
│       ├── security.yaml
│       ├── performance-reliability.yaml
│       ├── usability-accessibility.yaml
│       ├── compliance-governance.yaml
│       ├── data-provenance.yaml
│       ├── testing-validation.yaml
│       ├── deployment-operations.yaml
│       ├── safety-risk.yaml
│       └── ethics-ai-accountability.yaml
├── context/                   # SCD files
│   └── project/              # Project-tier SCDs
│       ├── system-context.yaml
│       ├── tech-stack.yaml
│       ├── integration-map.yaml
│       ├── component-model.yaml
│       ├── authn-authz.yaml
│       ├── data-protection.yaml
│       └── ... (30+ more SCDs)
├── docs/
│   └── GETTING_STARTED.md
├── .scs/
│   └── config
├── .gitignore
├── README.md
└── VERSION

Domain Bundles

Projects include 10 domain bundles covering:

1. Architecture: System design, tech stack, integrations, components
2. Security: Authentication, data protection, threat model
3. Performance & Reliability: Response time, availability, fault tolerance, scalability
4. Usability & Accessibility: UX principles, accessibility compliance, error handling
5. Compliance & Governance: Regulatory requirements (HIPAA, SOC2, etc.)
6. Data & Provenance: Data model, lineage tracking, retention policies
7. Testing & Validation: Test coverage, validation plans, QA procedures
8. Deployment & Operations: Infrastructure, observability, incident response
9. Safety & Risk: Risk assessment, safety checklists
10. Ethics & AI Accountability: AI usage policy, audit trails, bias mitigation

SCD Templates

Each SCD template includes:

• Proper YAML structure with id, type, version, status
• Domain and concern tags
• Comprehensive content placeholders with examples
• Provenance tracking
• Inline documentation and guidance

Project Types Comparison

Feature	Minimal	Standard	Healthcare	Fintech	SaaS	Government
Architecture SCDs	✓	✓	✓	✓	✓	✓
Security SCDs	✓	✓	✓	✓	✓	✓
Performance SCDs	-	✓	✓	✓	✓	✓
Compliance SCDs	-	✓	✓	✓	✓	✓
HIPAA/CHAI	-	-	✓	-	-	-
PCI-DSS/SOX	-	-	-	✓	-	-
GDPR	-	-	-	-	✓	-
NIST/FedRAMP	-	-	-	-	-	✓
Total SCDs	~11	~38	~38	~38	~38	~38

Validation

The scs validate command provides comprehensive validation:

Validation Levels

1. Syntax Validation - Ensures YAML/JSON is well-formed
2. Schema Validation - Validates against tier-specific JSON schemas
3. Semantic Validation - Checks type/tier matching, semver, provenance
4. Relationship Validation - Validates references between SCDs
5. Bundle Completeness - Ensures all required SCDs are present
6. Compliance Validation - Domain-specific requirement checks

Exit Codes

• 0 - Validation passed (no errors)
• 1 - Validation failed (errors found)
• 2 - Validation passed with warnings (when --strict enabled)
• 3 - Invalid command-line arguments
• 4 - File not found or permission error
• 5 - Internal validator error

What is SCS?

The Structured Context Specification (SCS) provides a standardized way to organize project context for AI-assisted development, compliance, and governance.

SCS enables:

• AI Context Injection: Provide LLMs with precise, relevant context
• Compliance Evidence: Map requirements to implementation
• Knowledge Management: Version-controlled project knowledge
• Team Alignment: Shared understanding of decisions and rationale
• Audit Trails: Track what was decided, when, and why

OICP Control Plane Integration

The scs-tools CLI creates and validates bundles locally (file-based workflow). For Context as a Service deployment, use the OICP Control Plane.

Publishing to OICP Control Plane

Once you've built and validated bundles locally, publish them to the OICP Registry:

# Build and validate locally
scs new project my-healthcare-app --type healthcare
cd my-healthcare-app
scs validate --bundle bundles/project-bundle.yaml

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

# Create tag for agents to subscribe to
curl -X POST http://localhost:8000/api/tags \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "my-app:latest",
    "bundle_id": "bundle:my-healthcare-app:1.0.0"
  }'

Context Streaming to AI Agents

Once published, AI agents can subscribe to your bundles:

# Agent subscribes to tag and receives context stream
import grpc
from context_service import context_service_pb2_grpc

stream = context_service.Subscribe(
    tag="my-app:latest",
    agent_id="agent-001"
)

# Agent receives context and automatic updates
for message in stream:
    # Use context in agent execution
    ...

Benefits of OICP Deployment:

• Real-time updates: Update context across all agents instantly (zero downtime)
• Perfect audit trail: Track what context each agent had at any timestamp
• Version management: Tags + semantic versioning (like Docker)
• Import resolution: Automatically resolve bundle dependencies

See Also:

• Control Plane README - OICP architecture and APIs
• Agent Integration Test Case - How agents use context
• Context Service README - gRPC streaming details

Common Workflows

Starting a New Healthcare Project

# Create project
scs new project patient-portal --type healthcare --author "Dr. Smith"
cd patient-portal

# Customize SCDs
# Edit context/project/system-context.yaml
# Edit context/project/hipaa-compliance.yaml
# Edit context/project/chai-adherence.yaml

# Validate your work
scs validate --bundle bundles/project-bundle.yaml

# Create versioned bundle for AI context
scs bundle create --name v1.0.0 --scds context/project/*.yaml

Adding SCS to Existing Project

# Navigate to your project
cd my-existing-project

# Initialize SCS
scs init --type saas

# Add specific domains you need
scs add bundle security --with-scds
scs add bundle compliance-governance --with-scds

# Customize for your project
# Edit the generated SCDs

# Validate
scs validate context/project/*.yaml

Incremental SCD Development

# Start minimal
scs new project mvp --type minimal

# Add SCDs as you need them
scs add scd system-context
scs add scd tech-stack
scs add scd authn-authz

# Validate incrementally
scs validate context/project/system-context.yaml

# When ready, add full domain
scs add bundle security --with-scds

# Validate complete bundle
scs validate --bundle bundles/project-bundle.yaml --strict

Examples

Healthcare Application

scs new project medication-adherence --type healthcare
cd medication-adherence

# The project includes:
# - HIPAA compliance SCDs
# - CHAI adherence SCDs
# - TEFCA interoperability SCDs
# - Standard security, architecture, operations

# Customize and validate
scs validate --bundle bundles/project-bundle.yaml

SaaS Product

scs new project todo-app --type saas
cd todo-app

# The project includes:
# - GDPR compliance SCDs
# - SOC2 controls
# - Multi-tenancy architecture
# - Standard security and operations

# Validate
scs validate --bundle bundles/project-bundle.yaml --strict

Minimal Prototype

scs new project mvp --type minimal
cd mvp

# Includes only essential SCDs:
# - System context
# - Tech stack
# - Authentication/authorization
# - Data protection
# - Deployment config
# - (11 core SCDs)

# Expand later with:
scs add bundle performance-reliability --with-scds
scs add bundle compliance-governance --with-scds

CI/CD Integration

GitHub Actions Example

name: Validate SCS

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install SCS Tools
        run: pip install scs-tools

      - name: Validate SCS Bundle
        run: |
          scs validate --bundle bundles/project-bundle.yaml \
            --strict \
            --output json > validation-report.json

      - name: Upload validation report
        uses: actions/upload-artifact@v3
        with:
          name: validation-report
          path: validation-report.json

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Validating SCS bundle..."
scs validate --bundle bundles/project-bundle.yaml --strict

if [ $? -ne 0 ]; then
  echo "❌ SCS validation failed"
  exit 1
fi

echo "✓ SCS validation passed"

Resources

• SCS Specification
• SCS Validator - Standalone validation tool
• Documentation
• Minimum Project SCDs
• Examples

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

See CONTRIBUTING.md for details.

License

MIT License - see LICENSE file for details

Support

• GitHub Issues
• Discussions

Version

Current version: 0.1.0

Changelog

0.1.0 (Initial Release)

• Project scaffolding with scs new project
• Project initialization with scs init
• Incremental SCD/bundle addition with scs add
• Bundle management with scs bundle
• Integrated validation with scs validate
• Support for 6 project types (minimal, standard, healthcare, fintech, saas, government)
• 38 SCD templates across 10 domains
• Jinja2 templating system
• Comprehensive documentation