AgentWorks

AgentWorks documentation

Workflow Manifest Architecture

Status

This migration is complete.

Workflow mode is now manifest-backed, and workflow.json is the source of truth for workflow definition.

Current reality:

The old migration-plan framing is obsolete.

Canonical File

Each workflow workspace has a top-level manifest:

The backend struct lives in workflow_manifest.go.

Current Manifest Shape

{
  "schema_version": 1,
  "version": "1.0.11",
  "id": "wf_ab12cd34",
  "label": "Customer onboarding",
  "objective": "Optional workflow-level objective",
  "success_criteria": "Optional workflow-level success criteria",
  "capabilities": {
    "selected_servers": ["github"],
    "selected_tools": [],
    "selected_skills": ["account-research"],
    "selected_secrets": ["my-secret-name"],
    "selected_global_secret_names": null,
    "browser_mode": "none",
    "use_code_execution_mode": false,
    "llm_config": {
      "schema_version": 2,
      "mode": "explicit",
      "builder_llm": {
        "provider": "openai",
        "model_id": "gpt-4.1"
      },
      "maintenance_llm": {
        "provider": "anthropic",
        "model_id": "claude-opus-4-8"
      },
      "pulse_llm": {
        "provider": "anthropic",
        "model_id": "claude-sonnet-5"
      },
      "tiered_config": {
        "tier_1": {
          "provider": "openai",
          "model_id": "gpt-4.1"
        },
        "tier_2": {
          "provider": "openai",
          "model_id": "gpt-4.1-mini"
        },
        "tier_3": {
          "provider": "openai",
          "model_id": "gpt-4.1-nano"
        }
      }
    }
  },
  "execution_defaults": {
    "always_use_same_run": false,
    "disable_learning": false,
    "global_skill_objective": "What the shared skill should capture",
    "disable_parallel_tool_execution": false,
    "execution_max_turns": 100,
    "enabled_custom_tools": ["workspace_advanced:*", "human_tools:*"]
  },
  "ownership": {
    "employee_id": null
  },
  "schedules": [
    {
      "id": "sched_123",
      "name": "Daily run",
      "cron_expression": "0 9 * * 1-5",
      "timezone": "Asia/Kolkata",
      "enabled": true,
      "group_ids": ["default"]
    }
  ],
  "created_at": "2026-04-09T10:00:00Z",
  "updated_at": "2026-04-09T10:00:00Z",
  "oversight_mode": "supervised",
  "decision_log_mutability": "append_only"
}

What Lives In The Manifest

capabilities

Workflow-wide execution defaults:

Notes:

execution_defaults

Workflow-level persistent execution defaults:

This is now the active home for global step overrides.

Runtime code reads global overrides from workflow.json.execution_defaults, not from planning/step_override.json.

ownership

Workflow assignment is manifest-backed now.

schedules

Schedules are manifest-backed now and no longer depend on DB workflow metadata.

Current schedule fields include:

For current runtime behavior, APIs, run history, and workshop-vs-workflow execution paths, see workflow_scheduling.md.

Auto-improvement framework fields

Two optional top-level fields configure hard behavioral gates the auto-improvement framework reads. All default to backward-compatible values; existing workflows can omit them.

Field Values Default Purpose
oversight_mode manual | supervised | autonomous supervised Controls when human approval is required for high-risk framework changes. Hard gate.
decision_log_mutability append_only | append_only_strict append_only append_only_strict forbids rewriting a dated decision entry in builder/improve.html, even for correction. Used by compliance workflows. Hard gate.

schema_version controls the JSON shape. version controls product-managed workflow behavior. The current 1.0.21 contract performs an idempotent artifact-ownership preflight before a scheduled workflow runs: it removes shared AgentWorks bridge/auth, Folder Guard, managed-tool, discovery, and coding-session mechanics from workflow-authored Plan/Learnings/KB prose while preserving semantic behavior and target-specific HOW. Ambiguous rewrites block the version stamp rather than guessing. The prior 1.0.20 contract remains the schema-5 executive Pulse journal upgrade.

The stable Goal lives only in soul/soul.md. /define-success records operating-model reasoning as a dated Reflection / Hansei entry in builder/improve.html; there is no permanent Workflow Profile card that can silently become an immutable constraint.

For the design rationale and worked examples, see auto_improvement_framework.md.

What Does Not Belong In The Manifest

Do not store live runtime/session state in workflow.json:

Do not store secret values:

Other Workflow Files

The manifest does not replace the rest of the workspace.

These still live alongside it:

workflow.json is the workflow-level definition file. The planning files are still the step graph and execution-plan files.

Runtime Flow

Discovery

Backend discovery uses DiscoverWorkflowManifests, which scans workspace folders and reads workflow.json.

CRUD APIs

Manifest routes are registered in server.go:

Execution bootstrap

Workflow execution loads manifest capabilities before running:

Workshop phase sessions also load manifest config directly:

Scheduling

The scheduler is manifest-based:

It scans workflow manifests, loads enabled schedules, and executes them without DB workflow dependency.

Frontend state

The frontend has a dedicated manifest store:

The old "workflow preset" view is now a compatibility layer built from manifests:

Current Compatibility Leftovers

A few migration-era leftovers still exist in code, but they are no longer the architecture:

These are compatibility remnants, not the main design.

Key Files