Enterprise Pilot Blueprint

Use this blueprint when you want to pilot SCC with one or two teams before a wider rollout.

SCC v1 is the governed runtime layer for AI coding agents. It standardizes how agents run, which plugins and MCP servers are allowed, how project configuration is inherited, and how developers can inspect the effective configuration.

Pilot Scope

Start with:

• one organization config;
• one or two team profiles;
• one real project per team;
• Claude Code and/or Codex as the approved providers;
• one network policy baseline;
• one documented exception process.

Do not start the pilot by designing a new project registry, identity platform, or plugin marketplace workflow. SCC already treats the current project as the repository/worktree being launched.

Baseline Controls

Surface	Pilot decision
Providers	Choose which teams can use Claude Code, Codex, or both
Plugins	Approve marketplaces and default plugins in org config
MCP servers	Allow only declared org/team/project MCP servers
Network policy	Set the org default, then let teams/projects tighten only
Dev environment commands	Use named dev_environment.commands; execute only with scc dev run <name> so audit and cwd bounds apply
Project config	Allow .scc.yaml only for teams that can support it
Exceptions	Use time-bounded local or policy exceptions

Note

Teams and projects can tighten inherited network_policy, but cannot loosen it. Looser values are ignored and shown by scc config explain under “Ignored Policy Changes”.

Rollout Steps

1. Create the org config.

   scc org init
   scc org validate org-config.json

2. Select a pilot team and verify its effective config.

   scc team switch backend
   scc config explain
   scc config explain --json

3. Add one project .scc.yaml only if the team needs project-specific additions.

   scc config validate
   scc config explain --field denied
   scc config explain --field network

4. Run a dry launch before asking developers to use the profile.

   scc start --dry-run --non-interactive ~/project

5. Capture troubleshooting artifacts during the pilot.

   scc support bundle
   scc support launch-audit
   scc support safety-audit

Executable Pilot Config

Start with one org config and one project config. Keep identifiers boring and auditable; the value is in repeatable inheritance, not a clever naming scheme.

org-config.json

{
  "schema_version": "1.0.0",
  "organization": {
    "name": "Example Municipality",
    "id": "example-muni"
  },
  "defaults": {
    "allowed_providers": ["claude", "codex"],
    "allowed_plugins": ["scc-safety-net", "internal-*"],
    "allowed_mcp_servers": ["*.example.gov"],
    "network_policy": "web-egress-enforced",
    "dev_environment": {
      "commands": {
        "test": {
          "argv": ["uv", "run", "pytest", "-q"],
          "working_directory": ".",
          "timeout_seconds": 120,
          "description": "Run the project test suite"
        }
      }
    },
    "session": {
      "timeout_hours": 8,
      "auto_resume": true
    }
  },
  "security": {
    "blocked_plugins": ["shadow-*"],
    "blocked_mcp_servers": ["*.personal.example"],
    "allow_stdio_mcp": false
  },
  "delegation": {
    "teams": {
      "allow_additional_plugins": ["internal-*"],
      "allow_additional_mcp_servers": ["casework"],
      "allow_dev_environment_commands": ["casework"]
    },
    "projects": {
      "inherit_team_delegation": true
    }
  },
  "profiles": {
    "casework": {
      "description": "Casework pilot team",
      "allowed_plugins": ["scc-safety-net"],
      "additional_plugins": ["internal-case-helper"],
      "additional_mcp_servers": [
        {
          "name": "casework",
          "type": "sse",
          "url": "https://casework.example.gov/mcp"
        }
      ],
      "delegation": {
        "allow_project_overrides": true
      }
    }
  }
}

.scc.yaml

additional_plugins:
  - internal-repo-linter

additional_mcp_servers:
  - name: project-docs
    type: sse
    url: https://docs.example.gov/mcp

# Projects may tighten inherited policy.
network_policy: locked-down-web

session:
  timeout_hours: 4

dev_environment:
  commands:
    test:
      argv: ["uv", "run", "pytest", "-q"]
      working_directory: "."
      timeout_seconds: 120
      description: "Run this repository's test suite"
  logs:
    api:
      argv: ["docker", "compose", "logs", "--tail", "100", "api"]
      timeout_seconds: 30
      description: "Read recent API logs"
  health_checks:
    api:
      argv: ["curl", "-fsS", "http://localhost:8000/health"]
      timeout_seconds: 10
      description: "Check local API health"

Run the pilot checks from the project repository:

scc org validate org-config.json
scc team switch casework
scc config validate
scc config explain
scc config explain --json
scc config explain --field network
scc config explain --field blocked
scc config explain --field denied
scc config explain --field dev_environment
scc dev status . --json
scc dev run test . --json
scc dev logs api . --json
scc dev health api . --json
scc start --provider claude --dry-run --json --non-interactive .
scc start --provider codex --dry-run --json --non-interactive .
scc support bundle

Expected review signals:

• effective provider is either claude or codex;
• effective team is casework;
• internal-case-helper and internal-repo-linter appear only if allowed by policy;
• looser network_policy attempts would appear under “Ignored Policy Changes”;
• dev_environment.commands, dev_environment.logs, and dev_environment.health_checks appear in explain/status output with fixed argv lists;
• scc dev status . --json reports the effective bridge contract without executing a host process;
• scc dev run test . --json, scc dev logs api . --json, and scc dev health api . --json write pre-execution audit events, return bounded stdout/stderr tails, and do not put stdout/stderr content in durable audit metadata;
• network MCP servers are blocked when the effective policy is locked-down-web;
• dry-run output contains the provider launch contract without starting Docker;
• support bundle manifest includes provider, runtime, policy, and work-context evidence.

Project Switching Model

In v1, project identity is the repository/worktree path that SCC launches, plus the selected team and provider. Quick resume uses that work context rather than a separate project registry.

For developers, the workflow is:

scc team switch backend
cd ~/project-a
scc start

scc team switch platform
cd ~/project-b
scc start --provider codex

Use .scc.yaml for project-specific additions, not for team selection. If a developer needs to change teams for a project, use scc team switch or scc start --team.

Audit Checks

For a pilot review, collect:

• scc config explain --json for each pilot team/project;
• scc doctor <project> --json for each devcontainer-based project;
• scc start --dry-run --json --non-interactive <project> for each provider;
• scc support bundle after representative launches;
• the org config and any project .scc.yaml files reviewed in the pilot.

Use these artifacts to answer:

• Which provider ran?
• Which team profile applied?
• Which plugins and MCP servers were active?
• Which additions were blocked, denied, or ignored?
• Which network policy was effective?
• Which named dev-environment commands were accepted, denied, ignored, or run?
• If launching from a devcontainer, did runtime_mount_source match the host-visible workspace path expected by the Docker daemon?
• For devcontainer or Compose projects, did the “Dev Environment Bridge” doctor check list the detected files and state that SCC does not mount the Docker socket into agent containers or attach them to arbitrary project networks?

For pilot machines that intentionally allow live Docker smoke checks, run:

SCC_REAL_RUNTIME_SMOKE=1 \
SCC_REAL_RUNTIME_IMAGE=scc-agent-claude:latest \
uv run pytest -q --no-cov -m real_runtime

This is optional. Normal SCC CI does not require Docker.

Not in v1

These are roadmap items, not pilot prerequisites:

• SSO, SAML federation, and SCIM provisioning;
• group-to-team, provider, policy profile, and admin-role entitlement mapping;
• provider credential brokering;
• read-only enterprise admin visibility;
• centralized SBOM export;
• CycloneDX inventory generation;
• running the agent inside the existing devcontainer;
• attaching the SCC agent container to arbitrary devcontainer or Compose service networks;
• a central project registry.

Caution

Do not promise these roadmap items as implemented controls in a pilot. Present SCC v1 as the governed runtime and configuration layer, then add identity, inventory, and deeper platform integrations once the runtime rollout is stable.

The planned identity work is tracked in Enterprise Identity Roadmap. That page is a future-state architecture note, not a current SCC v1 capability list.