feat(agent-platform): add GitOps AgentDefinition and ExecutionProfile catalog #950

Parent epic

• roadmap(agent-platform): agent definitions, execution profiles and governed agent creation .github#18

Depends on

• architecture(agent-platform): define AgentDefinition and ExecutionProfile contract mctl-agents#226 — canonical resource, lifecycle and source-of-truth contract.

Implementation may prepare fixtures/validation plumbing while the ADR is reviewed, but the public schema and catalog layout must not be finalized ahead of the architecture decision.

Existing baseline

• mctl-agents already has v1 AgentManifest files and a validator.
• mctl-api already stores immutable agent versions, per-environment releases, promotions and rollback (feat(agents): agent registry — versions, releases, promote/rollback mctl-api#126).
• mctl-gitops already owns Argo CWFTs, runtime deployment state and agent proposal state.

This issue must integrate those components. It must not create a parallel registry or duplicate existing release history.

Goal

Define and implement the GitOps-managed catalog representation for approved AgentDefinition and reusable ExecutionProfile resources, with schema/reference validation, safe defaults, lifecycle/versioning and reversible rollout.

Scope

• Define versioned schemas for AgentDefinition and ExecutionProfile according to fix(mctl-telegram): force client-side apply for oauth ExternalSecret #226.
• Choose and document canonical GitOps paths and ownership conventions for definitions, profiles and environment activation/release references.
• Provide initial definitions/profiles that map the current investigator, implementer and shepherd without behavior changes.
• Validate local and cross-resource references, including:
  • definition → execution profile;
  • model/profile identifiers;
  • skills/prompt sources;
  • tool/MCP allow-lists;
  • policy, budget, timeout and runtime/sandbox profiles;
  • Argo ClusterWorkflowTemplate references;
  • owner and lifecycle metadata.
• Define safe defaults. Missing or ambiguous security-sensitive fields must fail closed rather than expand access.
• Validate lifecycle transitions, immutable published versions and compatibility with the existing mctl-api registry.
• Define promotion, deprecation, disablement and rollback behavior without losing immutable execution provenance.
• Add CI/render validation and representative positive/negative fixtures.
• Document migration/import from current agents/_manifests and existing registry versions.

Safe-default requirements

At minimum, the design must explicitly decide and test defaults for:

• no implicit write tools or production mutations;
• no unbounded budget or timeout;
• no runtime without an approved sandbox/template;
• owner required;
• unknown model, skill, tool, policy or profile reference rejected;
• disabled/deprecated definition behavior;
• rollback to an exact previously published compatible version.

Non-goals

• Replacing the Postgres-backed registry or Temporal/Argo.
• Adding mctl-api catalog UI/MCP features beyond integration required for validation/publishing.
• Implementing the generic runtime resolver.
• Activating unreviewed definitions directly from a model action.
• Migrating every existing agent before the three-agent compatibility slice is proven.

Acceptance criteria

• Versioned schemas validate the contract approved in fix(mctl-telegram): force client-side apply for oauth ExternalSecret #226.
• Canonical GitOps catalog paths, owners and source-of-truth boundaries are documented.
• Investigator, implementer and shepherd fixtures/definitions validate and preserve their current effective model/tools/budget/runtime settings.
• All cross-resource references are checked deterministically in CI.
• Missing owner, unknown references, write-capable implicit defaults, unbounded budget/timeout and unsafe runtime configuration are rejected by tests.
• Lifecycle transitions and immutable version rules are enforced.
• Publish/promotion integrates with the existing mctl-api registry rather than creating a second release database.
• Rollback restores an exact prior compatible definition/profile set and preserves audit history.
• Existing AgentManifest/registry data has a documented, tested migration or compatibility path.
• Validation includes positive fixtures plus negative tests for broken references, incompatible versions and unsafe defaults.